trek 2.4.0 → 2.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (217) hide show
  1. checksums.yaml +4 -4
  2. data/.node-version +1 -1
  3. data/AGENTS.md +12 -8
  4. data/CHANGELOG.md +62 -0
  5. data/Gemfile +5 -0
  6. data/Gemfile.lock +205 -171
  7. data/Makefile +28 -1
  8. data/README.md +2 -2
  9. data/app/components/trek/dashboard/tile_component/tile_component.css +9 -0
  10. data/app/components/trek/dashboard/tile_component/tile_component.html.slim +4 -2
  11. data/app/components/trek/dashboard/tile_component.rb +12 -2
  12. data/app/components/trek/form/content_editor_component/content_editor_component.css +5 -0
  13. data/app/components/trek/form/content_editor_component/content_editor_component.html.slim +19 -93
  14. data/app/components/trek/form/content_editor_component/content_editor_component.js +94 -251
  15. data/app/components/trek/form/content_editor_component/extensions/block_view.js +40 -0
  16. data/app/components/trek/form/content_editor_component/extensions/image_block.js +28 -26
  17. data/app/components/trek/form/content_editor_component/extensions/prompts_block.js +15 -26
  18. data/app/components/trek/form/content_editor_component/extensions/table_of_contents.js +1 -3
  19. data/app/components/trek/form/content_editor_component.rb +15 -0
  20. data/app/components/trek/form/image_field_component/image_field_component.css +40 -1
  21. data/app/components/trek/form/image_field_component/image_field_component.html.slim +0 -9
  22. data/app/components/trek/form/image_field_component.rb +37 -14
  23. data/app/components/trek/list/item_component.rb +1 -1
  24. data/app/components/trek/list/tree/item_component.rb +2 -2
  25. data/app/components/trek/search_component/search_component.html.slim +2 -1
  26. data/app/components/trek/search_component.rb +9 -1
  27. data/app/content/trek/content/bullet_list.rb +10 -0
  28. data/app/content/trek/content/cleaner.rb +53 -0
  29. data/app/content/trek/content/document.rb +33 -0
  30. data/app/content/trek/content/image_block.rb +52 -0
  31. data/app/content/trek/content/link_resolver.rb +33 -0
  32. data/app/content/trek/content/list_item.rb +19 -0
  33. data/app/content/trek/content/ordered_list.rb +10 -0
  34. data/app/content/trek/content/paragraph.rb +10 -0
  35. data/app/content/trek/content/prompts_block.rb +21 -0
  36. data/app/content/trek/content.rb +38 -0
  37. data/app/controllers/concerns/trek/reorderable.rb +32 -3
  38. data/app/controllers/trek/csp_reports_controller.rb +17 -7
  39. data/app/controllers/trek/panels/base_controller.rb +3 -0
  40. data/app/controllers/trek/panels/links_controller.rb +1 -1
  41. data/app/controllers/trek/panels/prompts_controller.rb +2 -2
  42. data/app/controllers/trek/resource_controller.rb +5 -5
  43. data/app/helpers/trek/thumbnail_helper.rb +11 -0
  44. data/app/jobs/trek/purge_expired_sessions_job.rb +4 -3
  45. data/app/models/concerns/trek/contentable.rb +19 -10
  46. data/app/models/concerns/trek/pageable.rb +10 -1
  47. data/app/models/concerns/trek/users/sign_in_code.rb +70 -0
  48. data/app/models/concerns/trek/users/sign_in_lockout.rb +4 -2
  49. data/app/views/trek/panels/images/_form.html.slim +1 -1
  50. data/app/views/trek/panels/images/create.turbo_stream.slim +1 -1
  51. data/app/views/trek/panels/links/_form.html.slim +3 -5
  52. data/app/views/trek/panels/prompts/_form.html.slim +1 -1
  53. data/app/views/trek/panels/prompts/create.turbo_stream.slim +0 -1
  54. data/config/locales/trek.en.yml +40 -2
  55. data/config/locales/trek.fr.yml +40 -2
  56. data/docs/.vitepress/config.mjs +4 -1
  57. data/docs/background-jobs.md +69 -0
  58. data/docs/content-editor.md +219 -0
  59. data/docs/customize.md +2 -0
  60. data/docs/deploy.md +2 -2
  61. data/docs/getting-started.md +4 -4
  62. data/docs/index.md +1 -1
  63. data/docs/reference/components.md +2 -2
  64. data/docs/reference/concerns/contentable.md +11 -4
  65. data/docs/reference/concerns/formattable.md +1 -1
  66. data/docs/reference/controllers.md +1 -1
  67. data/docs/reference/environment-variables.md +1 -0
  68. data/docs/reference/formatters.md +4 -9
  69. data/docs/reference/forms.md +1 -1
  70. data/docs/reference/generators/audit-log.md +2 -2
  71. data/docs/reference/generators/install.md +3 -2
  72. data/docs/reference/generators/public-accounts.md +141 -0
  73. data/docs/reference/generators/security-headers.md +1 -1
  74. data/docs/reference/index.md +2 -1
  75. data/docs/reference/models/fragment.md +1 -0
  76. data/docs/reference/models/user.md +3 -1
  77. data/docs/what-is-trek.md +5 -5
  78. data/lib/generators/trek/audit_log_generator.rb +54 -0
  79. data/lib/generators/trek/helpers.rb +13 -5
  80. data/lib/generators/trek/install/admin/users_generator.rb +6 -1
  81. data/lib/generators/trek/install/admin_generator.rb +8 -0
  82. data/lib/generators/trek/install/appsignal_generator.rb +1 -1
  83. data/lib/generators/trek/install/audit_log_generator.rb +9 -45
  84. data/lib/generators/trek/install/authentication_generator.rb +1 -1
  85. data/lib/generators/trek/install/authorization_generator.rb +1 -1
  86. data/lib/generators/trek/install/good_job_generator.rb +161 -0
  87. data/lib/generators/trek/install/model_specs_generator.rb +3 -3
  88. data/lib/generators/trek/install/postmark_generator.rb +2 -2
  89. data/lib/generators/trek/install/ruby_generator.rb +1 -1
  90. data/lib/generators/trek/install/scalingo_generator.rb +7 -45
  91. data/lib/generators/trek/install/specs_generator.rb +11 -0
  92. data/lib/generators/trek/install/user_generator.rb +1 -1
  93. data/lib/generators/trek/install_generator.rb +15 -0
  94. data/lib/generators/trek/public_accounts_generator.rb +267 -0
  95. data/lib/generators/trek/scaffold_generator.rb +13 -5
  96. data/lib/generators/trek/scalingo_generator.rb +55 -0
  97. data/lib/generators/trek/templates/.gitlab-ci.yml +1 -1
  98. data/lib/generators/trek/templates/Makefile +1 -1
  99. data/lib/generators/trek/templates/controllers/admin/fragments_controller.rb +7 -0
  100. data/lib/generators/trek/templates/controllers/admin/panels/images_controller.rb +8 -0
  101. data/lib/generators/trek/templates/controllers/admin/panels/links_controller.rb +8 -0
  102. data/lib/generators/trek/templates/controllers/admin/panels/prompts_controller.rb +8 -0
  103. data/lib/generators/trek/templates/controllers/admin/password_renewals_controller.rb +11 -0
  104. data/lib/generators/trek/templates/controllers/admin/user_sessions_controller.rb +1 -1
  105. data/lib/generators/trek/templates/controllers/admin/users_controller.rb +0 -8
  106. data/lib/generators/trek/templates/initializers/content_security_policy.rb +3 -2
  107. data/lib/generators/trek/templates/initializers/good_job.rb.tt +38 -0
  108. data/lib/generators/trek/templates/jobs/mail_delivery_job.rb +6 -0
  109. data/lib/generators/trek/templates/layouts/admin.html.slim +5 -0
  110. data/lib/generators/trek/templates/mailers/admin_mailer.rb +4 -2
  111. data/lib/generators/trek/templates/models/fragment.rb +14 -0
  112. data/lib/generators/trek/templates/package.json.tt +1 -1
  113. data/lib/generators/trek/templates/public_accounts/api/authentication.rb.tt +76 -0
  114. data/lib/generators/trek/templates/public_accounts/api/controllers/accounts_controller.rb.tt +22 -0
  115. data/lib/generators/trek/templates/public_accounts/api/controllers/active_sessions_controller.rb.tt +21 -0
  116. data/lib/generators/trek/templates/public_accounts/api/controllers/base_controller.rb.tt +71 -0
  117. data/lib/generators/trek/templates/public_accounts/api/controllers/email_changes_controller.rb.tt +55 -0
  118. data/lib/generators/trek/templates/public_accounts/api/controllers/email_confirmations_controller.rb.tt +19 -0
  119. data/lib/generators/trek/templates/public_accounts/api/controllers/password_resets_controller.rb.tt +28 -0
  120. data/lib/generators/trek/templates/public_accounts/api/controllers/passwords_controller.rb.tt +17 -0
  121. data/lib/generators/trek/templates/public_accounts/api/controllers/registrations_controller.rb.tt +17 -0
  122. data/lib/generators/trek/templates/public_accounts/api/controllers/sessions_controller.rb.tt +45 -0
  123. data/lib/generators/trek/templates/public_accounts/api/controllers/sign_in_codes_controller.rb.tt +15 -0
  124. data/lib/generators/trek/templates/public_accounts/jobs/sign_in_code_job.rb.tt +13 -0
  125. data/lib/generators/trek/templates/public_accounts/locales/accounts.en.yml.tt +205 -0
  126. data/lib/generators/trek/templates/public_accounts/locales/accounts.fr.yml.tt +205 -0
  127. data/lib/generators/trek/templates/public_accounts/mailers/account_mailer.rb.tt +85 -0
  128. data/lib/generators/trek/templates/public_accounts/migrations/create_accounts.rb.tt +46 -0
  129. data/lib/generators/trek/templates/public_accounts/models/account/session.rb.tt +47 -0
  130. data/lib/generators/trek/templates/public_accounts/models/account/sign_in_code.rb.tt +8 -0
  131. data/lib/generators/trek/templates/public_accounts/models/account.rb.tt +73 -0
  132. data/lib/generators/trek/templates/public_accounts/spec/api/accounts_spec.rb.tt +90 -0
  133. data/lib/generators/trek/templates/public_accounts/spec/api/sign_ins_spec.rb.tt +158 -0
  134. data/lib/generators/trek/templates/public_accounts/spec/models/account/sign_in_code_spec.rb.tt +56 -0
  135. data/lib/generators/trek/templates/public_accounts/spec/models/account_spec.rb.tt +109 -0
  136. data/lib/generators/trek/templates/public_accounts/spec/web/accounts_spec.rb.tt +126 -0
  137. data/lib/generators/trek/templates/public_accounts/spec/web/authentication_spec.rb.tt +43 -0
  138. data/lib/generators/trek/templates/public_accounts/spec/web/sign_ins_spec.rb.tt +215 -0
  139. data/lib/generators/trek/templates/public_accounts/views/mailer/email_change.en.html.slim.tt +10 -0
  140. data/lib/generators/trek/templates/public_accounts/views/mailer/email_change.en.text.erb.tt +8 -0
  141. data/lib/generators/trek/templates/public_accounts/views/mailer/email_change.fr.html.slim.tt +13 -0
  142. data/lib/generators/trek/templates/public_accounts/views/mailer/email_change.fr.text.erb.tt +8 -0
  143. data/lib/generators/trek/templates/public_accounts/views/mailer/email_change_code.en.html.slim.tt +9 -0
  144. data/lib/generators/trek/templates/public_accounts/views/mailer/email_change_code.en.text.erb.tt +11 -0
  145. data/lib/generators/trek/templates/public_accounts/views/mailer/email_change_code.fr.html.slim.tt +11 -0
  146. data/lib/generators/trek/templates/public_accounts/views/mailer/email_change_code.fr.text.erb.tt +11 -0
  147. data/lib/generators/trek/templates/public_accounts/views/mailer/email_confirmation.en.html.slim.tt +10 -0
  148. data/lib/generators/trek/templates/public_accounts/views/mailer/email_confirmation.en.text.erb.tt +8 -0
  149. data/lib/generators/trek/templates/public_accounts/views/mailer/email_confirmation.fr.html.slim.tt +10 -0
  150. data/lib/generators/trek/templates/public_accounts/views/mailer/email_confirmation.fr.text.erb.tt +8 -0
  151. data/lib/generators/trek/templates/public_accounts/views/mailer/password_reset.en.html.slim.tt +10 -0
  152. data/lib/generators/trek/templates/public_accounts/views/mailer/password_reset.en.text.erb.tt +8 -0
  153. data/lib/generators/trek/templates/public_accounts/views/mailer/password_reset.fr.html.slim.tt +13 -0
  154. data/lib/generators/trek/templates/public_accounts/views/mailer/password_reset.fr.text.erb.tt +8 -0
  155. data/lib/generators/trek/templates/public_accounts/views/mailer/sign_in_code.en.html.slim.tt +9 -0
  156. data/lib/generators/trek/templates/public_accounts/views/mailer/sign_in_code.en.text.erb.tt +11 -0
  157. data/lib/generators/trek/templates/public_accounts/views/mailer/sign_in_code.fr.html.slim.tt +9 -0
  158. data/lib/generators/trek/templates/public_accounts/views/mailer/sign_in_code.fr.text.erb.tt +11 -0
  159. data/lib/generators/trek/templates/public_accounts/views/mailer/sign_in_locked.en.html.slim.tt +23 -0
  160. data/lib/generators/trek/templates/public_accounts/views/mailer/sign_in_locked.en.text.erb.tt +14 -0
  161. data/lib/generators/trek/templates/public_accounts/views/mailer/sign_in_locked.fr.html.slim.tt +24 -0
  162. data/lib/generators/trek/templates/public_accounts/views/mailer/sign_in_locked.fr.text.erb.tt +14 -0
  163. data/lib/generators/trek/templates/public_accounts/web/authentication.rb.tt +97 -0
  164. data/lib/generators/trek/templates/public_accounts/web/controllers/accounts_controller.rb.tt +33 -0
  165. data/lib/generators/trek/templates/public_accounts/web/controllers/active_sessions_controller.rb.tt +15 -0
  166. data/lib/generators/trek/templates/public_accounts/web/controllers/base_controller.rb.tt +52 -0
  167. data/lib/generators/trek/templates/public_accounts/web/controllers/email_changes_controller.rb.tt +85 -0
  168. data/lib/generators/trek/templates/public_accounts/web/controllers/email_confirmations_controller.rb.tt +19 -0
  169. data/lib/generators/trek/templates/public_accounts/web/controllers/password_resets_controller.rb.tt +41 -0
  170. data/lib/generators/trek/templates/public_accounts/web/controllers/passwords_controller.rb.tt +23 -0
  171. data/lib/generators/trek/templates/public_accounts/web/controllers/registrations_controller.rb.tt +24 -0
  172. data/lib/generators/trek/templates/public_accounts/web/controllers/sessions_controller.rb.tt +78 -0
  173. data/lib/generators/trek/templates/public_accounts/web/controllers/sign_in_codes_controller.rb.tt +27 -0
  174. data/lib/generators/trek/templates/public_accounts/web/views/_flash.html.slim.tt +5 -0
  175. data/lib/generators/trek/templates/public_accounts/web/views/accounts/show.html.slim.tt +52 -0
  176. data/lib/generators/trek/templates/public_accounts/web/views/email_changes/edit.html.slim.tt +17 -0
  177. data/lib/generators/trek/templates/public_accounts/web/views/email_changes/new.html.slim.tt +15 -0
  178. data/lib/generators/trek/templates/public_accounts/web/views/password_resets/edit.html.slim.tt +26 -0
  179. data/lib/generators/trek/templates/public_accounts/web/views/password_resets/new.html.slim.tt +15 -0
  180. data/lib/generators/trek/templates/public_accounts/web/views/passwords/edit.html.slim.tt +25 -0
  181. data/lib/generators/trek/templates/public_accounts/web/views/registrations/new.html.slim.tt +28 -0
  182. data/lib/generators/trek/templates/public_accounts/web/views/sessions/new.html.slim.tt +38 -0
  183. data/lib/generators/trek/templates/public_accounts/web/views/sign_in_codes/new.html.slim.tt +17 -0
  184. data/lib/generators/trek/templates/spec/jobs/mail_delivery_job_spec.rb +11 -0
  185. data/lib/generators/trek/templates/spec/mailers/admin_mailer_spec.rb +12 -1
  186. data/lib/generators/trek/templates/spec/requests/admin/active_sessions_spec.rb +1 -0
  187. data/lib/generators/trek/templates/spec/requests/admin/fragments_spec.rb +27 -3
  188. data/lib/generators/trek/templates/spec/requests/admin/good_job_spec.rb +34 -0
  189. data/lib/generators/trek/templates/spec/requests/admin/pages_spec.rb +9 -1
  190. data/lib/generators/trek/templates/spec/requests/admin/panels_spec.rb +70 -0
  191. data/lib/generators/trek/templates/spec/requests/admin/password_renewal_spec.rb +2 -2
  192. data/lib/generators/trek/templates/spec/requests/admin/sign_in_lockout_spec.rb +1 -1
  193. data/lib/generators/trek/templates/spec/requests/admin/sign_in_notices_spec.rb +5 -3
  194. data/lib/generators/trek/templates/spec/requests/admin/user_sessions_spec.rb +2 -2
  195. data/lib/generators/trek/templates/views/admin/fragments/index.html.slim +14 -3
  196. data/lib/generators/trek/templates/views/admin/users/index.html.slim +1 -1
  197. data/lib/generators/trek/templates/views/admin_mailer/new_sign_in.en.html.slim +1 -1
  198. data/lib/generators/trek/templates/views/admin_mailer/new_sign_in.en.text.erb +1 -1
  199. data/lib/generators/trek/templates/views/admin_mailer/new_sign_in.fr.html.slim +1 -1
  200. data/lib/generators/trek/templates/views/admin_mailer/new_sign_in.fr.text.erb +1 -1
  201. data/lib/trek/csp_reports.rb +22 -4
  202. data/lib/trek/engine.rb +8 -3
  203. data/lib/trek/saved_attachments_reload.rb +2 -1
  204. data/lib/trek/typography_formatter.rb +35 -4
  205. data/lib/trek/version.rb +1 -1
  206. data/lib/trek.rb +1 -1
  207. data/package.json +12 -8
  208. data/renovate.json +1 -0
  209. data/trek.gemspec +3 -3
  210. data/vitest.config.mjs +24 -0
  211. data/yarn.lock +1706 -1028
  212. metadata +116 -14
  213. data/app/formatters/prosemirror_to_html/global_id_to_links_formatter.rb +0 -19
  214. data/app/formatters/prosemirror_to_html/nodes/image_block.rb +0 -44
  215. data/app/formatters/prosemirror_to_html/nodes/prompts_block.rb +0 -28
  216. data/app/formatters/prosemirror_to_html/remove_empty_paragraphs_formatter.rb +0 -11
  217. data/app/models/prosemirror.rb +0 -23
@@ -0,0 +1,219 @@
1
+ # Content editor
2
+
3
+ Trek's content editor is where the admin writes the content of pages, page versions and fragments: headings, lists, quotes, links, images and calls to action, laid out as they will read.
4
+
5
+ It's built on [Tiptap](https://tiptap.dev), an editor framework on top of [ProseMirror](https://prosemirror.net). That's why the editor doesn't save HTML. It saves a structured document: a tree of typed nodes (paragraphs, headings, images…) and marks (bold, links…), each with typed attributes. The site turns that document into HTML when it shows it, with the [`prosemirror`](https://github.com/etaminstudio/prosemirror) gem.
6
+
7
+ Keeping structure rather than markup lets Trek:
8
+
9
+ - **render the content safely:** the HTML is built from known types, so content can't inject markup;
10
+ - **change how a block looks** on the site without touching stored content, for example images rendered by the app's own component;
11
+ - **keep links to pages working** when they move: a link stores the page, not its URL;
12
+ - **read the content as data:** extract its text, search it, check it.
13
+
14
+ This guide follows content from end to end:
15
+
16
+ 1. **Editing:** [using the editor](#using-the-editor) in admin forms, and its panels.
17
+ 2. **Storage:** [how content is stored](#how-content-is-stored), as JSON in a `jsonb` column.
18
+ 3. **Rendering:** [rendering on the site](#rendering-on-the-site), through `Trek::Content.schema`, and [customizing it](#customizing-the-rendering).
19
+
20
+ ## Using the editor
21
+
22
+ Add it to an admin form with `f.content_editor`:
23
+
24
+ ```slim
25
+ = form_with model: [:admin, @book] do |f|
26
+ = f.group :content
27
+ = f.content_editor :content
28
+ ```
29
+
30
+ | Option | Default | Effect |
31
+ | --- | --- | --- |
32
+ | `nodes` | `true` | the toolbar's text buttons: bold, italic, link, clear formatting, line break |
33
+ | `blocks` | `true` | the toolbar's block buttons: paragraph, headings 2 to 4, bullet list, quote, horizontal rule |
34
+ | `floating` | `true` | the menu on an empty line, inserting an image or a prompt |
35
+ | `autofocus` | `false` | puts the cursor at the end of the content on load |
36
+
37
+ Undo and redo are always there. For a short field, such as an introduction, turn the rest off:
38
+
39
+ ```slim
40
+ = f.content_editor :intro, blocks: false, floating: false
41
+ ```
42
+
43
+ Tiptap's Markdown shortcuts work too: typing `1. ` starts an ordered list, and `~~text~~` strikes text through, even though the toolbar has no button for them. The site renders them like the rest.
44
+
45
+ ### Links
46
+
47
+ The link button opens a panel to pick a page of the site, or type any URL. A link to a page is stored as its GlobalID (`gid://app/Page/12`) rather than its URL. It's turned into a URL when the content is rendered, so the link survives the page moving or changing its slug (see [Links to records with GlobalID](https://github.com/etaminstudio/prosemirror/blob/main/COOKBOOK.md#links-to-records-with-globalid) in the `prosemirror` gem's cookbook).
48
+
49
+ ### Images
50
+
51
+ The image entry of the floating menu opens a panel to upload an image (with Uppy, stored by Shrine's `ModelImageUploader`). The panel also sets its alternative text, caption, credit and size (`default` or `larger`). The node keeps the uploaded file's data, so the image belongs to the content, not to a record.
52
+
53
+ ### Prompts
54
+
55
+ The prompt entry inserts a call to action: a text, a link (a page or a URL, as for links), where it opens, and a title.
56
+
57
+ ### Panels
58
+
59
+ The link, image and prompt panels are the `Admin::Panels::*` controllers that the installer generates (see [Controllers](/reference/controllers)).
60
+
61
+ ## How content is stored
62
+
63
+ The editor saves a ProseMirror document in the form's field, as JSON, with Tiptap's camelCase type names:
64
+
65
+ ```json
66
+ {
67
+ "type": "doc",
68
+ "content": [
69
+ { "type": "heading", "attrs": { "level": 2 }, "content": [{ "type": "text", "text": "Opening hours" }] },
70
+ {
71
+ "type": "paragraph",
72
+ "content": [
73
+ { "type": "text", "text": "See the " },
74
+ { "type": "text", "text": "map", "marks": [{ "type": "link", "attrs": { "href": "gid://app/Page/12" } }] }
75
+ ]
76
+ },
77
+ { "type": "imageBlock", "attrs": { "file_data": "{\"id\":\"…\",\"storage\":\"store\"}", "alt": "The entrance", "text": "Main entrance", "credit": "Photo: A. Smith", "size": "larger" } }
78
+ ]
79
+ }
80
+ ```
81
+
82
+ - **Column:** Trek's models keep it in a `jsonb` `content` column. [Translatable](/reference/concerns/translatable) models hold one document per locale.
83
+ - **Cleaning:** before saving, [Contentable](/reference/concerns/contentable) removes what rendering skips: empty paragraphs, empty list items, and lists left empty. An empty document keeps one paragraph, and whatever the schema doesn't know is kept. The editor submits the content as a JSON string, and it's stored as a document. Empty paragraphs used for spacing are removed for good.
84
+ - **Typography:** [Formattable](/reference/concerns/formattable) works on documents, changing only their text nodes. Add `:content` to the generated `format_attributes Trek::TypographyFormatter, :title, :description` to apply French typography to it.
85
+ - **Search:** to find content by its words, search the text nodes rather than the JSON, or every document matches `paragraph`. `content_text` gives the plain text, and `Fragment.search` shows a query in SQL (see [Fragment](/reference/models/fragment)).
86
+
87
+ ## Rendering on the site
88
+
89
+ A model with a `content` column includes [Contentable](/reference/concerns/contentable):
90
+
91
+ ```slim
92
+ / ERB or Slim
93
+ = @page.formatted_content
94
+ ```
95
+
96
+ ```ruby
97
+ # Phlex
98
+ render @page.content_document.to_phlex
99
+ ```
100
+
101
+ For a [versioned](/reference/concerns/versionable) page, render its live version's content, `current_content`, which comes from a `PageVersion`: `Trek::Content::Document.parse(@page.current_version || @page, @page.current_content).to_html`.
102
+
103
+ `formatted_content` only reads the `content` column. To render another column, such as a book's `intro`, parse it with `Trek::Content::Document`. Its first argument is the record holding the content: when that content is invalid, the error reports name the record (`trek_content: "Book#3"`, see [Invalid content](#invalid-content)), so you know which one to fix.
104
+
105
+ ```ruby
106
+ Trek::Content::Document.parse(book, book.intro).to_html
107
+ ```
108
+
109
+ ### What the HTML contains
110
+
111
+ - **Escaping:** HTML is escaped as it is built. Nothing a user types can open a tag.
112
+ - **Attributes** are typed: a value that doesn't fit, such as a heading level of 9, is replaced by its default, or removed.
113
+ - **URLs:** links and images only allow `http`, `https`, `mailto`, `tel` and relative URLs.
114
+ - **Links to pages** become the page's URL, through `url_for`. The records a document links to load together, with one query per model. A link to a deleted record is removed, and its text kept.
115
+ - **Empty nodes:** empty paragraphs, empty list items, and lists with only empty items render nothing ([Skip empty paragraphs](https://github.com/etaminstudio/prosemirror/blob/main/COOKBOOK.md#skip-empty-paragraphs)). Saving removes them from the stored content too ([cleaning](#how-content-is-stored)), but content saved before Trek did is only cleaned when it's saved again.
116
+ - **Images** render as a `<figure>` with a `data-size` attribute, with the caption and the credit in its `<figcaption>`.
117
+ - **Prompts** render as a link.
118
+ - **Unknown attributes,** such as heading ids added by the editor, are kept in the JSON but never rendered. To give headings anchors, see [Heading anchors](https://github.com/etaminstudio/prosemirror/blob/main/COOKBOOK.md#heading-anchors) in the `prosemirror` gem's cookbook.
119
+
120
+ ### Invalid content
121
+
122
+ A document that doesn't fit the schema is fixed as it's read, and each problem is reported to `Rails.error` (`handled: true`):
123
+
124
+ - an attribute of the wrong type is converted when the meaning is clear, or replaced by its default, or its node or mark is removed (a link keeps its text);
125
+ - a node of an unknown type renders only its content;
126
+ - links to deleted records, reported as `Prosemirror::UnresolvedURL`.
127
+
128
+ The report's context names the record holding the content (`trek_content: "Page#12"`), which AppSignal shows as a tag, so a problem leads back to the page to fix.
129
+
130
+ ## Customizing the rendering
131
+
132
+ `Trek::Content.schema` is Tiptap's schema (`Prosemirror::Schema.tiptap(case: :camel)`), with Trek's own node types:
133
+
134
+ | Node type | Role |
135
+ | --- | --- |
136
+ | `Trek::Content::Paragraph` | skips empty paragraphs |
137
+ | `Trek::Content::ListItem` | skips empty list items, with no content or only empty paragraphs |
138
+ | `Trek::Content::BulletList`, `OrderedList` | skip lists with only empty items |
139
+ | `Trek::Content::ImageBlock` | renders image blocks as a `<figure>`: the image, its caption and credit |
140
+ | `Trek::Content::PromptsBlock` | renders prompt blocks as a link |
141
+
142
+ Node and mark types are [Phlex](https://www.phlex.fun) components with [Literal](https://literal.fun) properties (see the [`prosemirror` README](https://github.com/etaminstudio/prosemirror#custom-nodes-and-marks)). To change how one renders, subclass it, and put it in the schema from an initializer. The cookbook's [Render your own components](https://github.com/etaminstudio/prosemirror/blob/main/COOKBOOK.md#render-your-own-components) shows the pattern.
143
+
144
+ ### Images with the app's component
145
+
146
+ For example, images at the app's own sizes:
147
+
148
+ ```ruby
149
+ # app/content/image_block.rb
150
+ class ImageBlock < Trek::Content::ImageBlock
151
+ def view_template
152
+ return unless image
153
+
154
+ render Components::Figure.new(
155
+ src: image.derivation_url(:thumbnail, 930, 1200),
156
+ alt: @alt,
157
+ caption: @text,
158
+ credit: @credit
159
+ )
160
+ end
161
+ end
162
+ ```
163
+
164
+ ```ruby
165
+ # config/initializers/trek.rb
166
+ Rails.application.config.to_prepare do
167
+ Trek::Content.schema = Trek::Content.default_schema.with(ImageBlock)
168
+ end
169
+ ```
170
+
171
+ - **Registering:** `with` replaces the type of the same name, and keeps the others.
172
+ - **Reloading:** the default schema is rebuilt after code reloading, so `to_prepare` sees the reloaded classes in development.
173
+ - **Inside a node type:**
174
+ - the node's attributes are instance variables (`@alt`, `@text`);
175
+ - `image` is the uploaded file, or `nil` when the data is missing or invalid;
176
+ - `safe_url(url)` checks a URL against the allowed schemes.
177
+
178
+ ### Prompts as the app's buttons
179
+
180
+ ```ruby
181
+ class PromptsBlock < Trek::Content::PromptsBlock
182
+ def view_template
183
+ href = @href.present? && safe_url(@href)
184
+ return if !href || @text.blank?
185
+
186
+ render Components::Button.new(href:, target: @target, title: @title) { @text }
187
+ end
188
+ end
189
+ ```
190
+
191
+ Register it the same way: `Trek::Content.default_schema.with(ImageBlock, PromptsBlock)`.
192
+
193
+ ### Node types of the app's own
194
+
195
+ A node of a type the schema doesn't know renders only its content, and is reported. To render it, add a class of that name to the schema (`Callout` for `callout`):
196
+
197
+ ```ruby
198
+ class Callout < Prosemirror::NodeType
199
+ group :block
200
+ content "block+"
201
+
202
+ prop :tone, _Union?("info", "warning")
203
+
204
+ def view_template(&) = aside(data_tone: @tone, &)
205
+ end
206
+ ```
207
+
208
+ Trek's editor has a fixed set of Tiptap extensions, so it can't insert such a node yet. It renders nodes that come from elsewhere: imported content, or JSON written by a script.
209
+
210
+ ## Importing content
211
+
212
+ The `prosemirror` gem builds documents from HTML (with the `herb` gem), Markdown (with `commonmarker`) or plain text, using the schema's parse rules. To fill pages from an older site:
213
+
214
+ ```ruby
215
+ document = Prosemirror.from_html(old_html, schema: Trek::Content.schema)
216
+ page.update!(content: document.to_h)
217
+ ```
218
+
219
+ `to_h` gives the JSON the editor reads, with invalid parts fixed. See the [`prosemirror` README](https://github.com/etaminstudio/prosemirror#html-import) for what each import keeps.
data/docs/customize.md CHANGED
@@ -48,6 +48,8 @@ Trek's UI components accept options where it matters:
48
48
  f.content_editor :intro, nodes: false, floating: false
49
49
  ```
50
50
 
51
+ To render content blocks with your own components, see [Customizing the rendering](/content-editor#customizing-the-rendering).
52
+
51
53
  - **`Trek::LayoutComponent`** — use the `panel` slot to add your own side panel to admin screens.
52
54
 
53
55
  ## Models
data/docs/deploy.md CHANGED
@@ -17,7 +17,7 @@ Compared with the stock buildpacks, deploys typically go from around 3 minutes t
17
17
  Generate the Scalingo files (an `Aptfile` and a `Procfile` with the web process and post-deploy migrations):
18
18
 
19
19
  ```sh
20
- rails g trek:install:scalingo
20
+ rails g trek:scalingo
21
21
  ```
22
22
 
23
23
  Then configure the Scalingo app's environment, pinning the buildpack to a release through its archive:
@@ -57,7 +57,7 @@ Before going live, check what Trek expects from the hosting: backups, a shared c
57
57
 
58
58
  Apps deployed with the stock `.buildpacks` (apt + ruby) migrate in three steps:
59
59
 
60
- 1. delete `.buildpacks` (re-running `rails g trek:install:scalingo` does it) and check that `.node-version` exists — apps generated with `rails new -j esbuild` have it
60
+ 1. delete `.buildpacks` (re-running `rails g trek:scalingo` does it) and check that `.node-version` exists — apps generated with `rails new -j esbuild` have it
61
61
  2. set `BUILDPACK_URL` as above, and map `DATABASE_URL` if the app doesn't read it yet
62
62
  3. deploy — the first build fills the caches, the next ones benefit from them
63
63
 
@@ -6,8 +6,8 @@ This guide takes you from an empty directory to a working Rails application with
6
6
 
7
7
  Make sure the following are installed:
8
8
 
9
- - Ruby 3.1+
10
- - Rails 7.0+
9
+ - Ruby 3.3+
10
+ - Rails 8.0+
11
11
  - PostgreSQL 12+
12
12
  - Node 22+
13
13
  - Yarn 4.x
@@ -19,7 +19,7 @@ Check your Rails version:
19
19
  rails -v
20
20
  ```
21
21
 
22
- If it's older than 7.0, run `gem install rails` to upgrade.
22
+ If it's older than 8.0, run `gem install rails` to upgrade.
23
23
 
24
24
  Check your Yarn version:
25
25
 
@@ -132,4 +132,4 @@ Next steps:
132
132
 
133
133
  - [Customize Trek](/customize) — branding, favicon, components
134
134
  - [Reference manual](/reference/) — generators, models, components and more
135
- - [Deploying to Scalingo](/deploy) — `trek:install:scalingo`, a few environment variables, and the dedicated trek-buildpack handles the rest
135
+ - [Deploying to Scalingo](/deploy) — `trek:scalingo`, a few environment variables, and the dedicated trek-buildpack handles the rest
data/docs/index.md CHANGED
@@ -23,7 +23,7 @@ features:
23
23
  details: One installer sets up authentication, authorization, file uploads, emails, i18n and a polished admin UI — with sensible conventions you can override later.
24
24
  - icon: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" width="32" height="32" aria-hidden="true"><path fill-rule="evenodd" fill="var(--trek-icon-ink, currentColor)" d="M6 6H30V30A12 12 0 0 1 18 42H6ZM12 14H24V18H12ZM12 22H20V26H12Z"/><path fill="var(--trek-icon-accent, #63E0A6)" d="M34 6H42V32A4 4 0 0 1 34 32Z"/></svg>'
25
25
  title: Modern content editing
26
- details: A Tiptap-based rich text editor, hierarchical pages with versioning and SEO-friendly paths, plus reusable content fragments.
26
+ details: A Tiptap-based content editor, hierarchical pages with versioning and SEO-friendly paths, plus reusable content fragments.
27
27
  - icon: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" width="32" height="32" aria-hidden="true"><path fill-rule="evenodd" fill="var(--trek-icon-ink, currentColor)" d="M6 18H30V30H42V42H6Z"/><path fill="var(--trek-icon-accent, #63E0A6)" d="M6 18V6A12 12 0 0 1 18 18Z"/></svg>'
28
28
  title: Scaffold-driven development
29
29
  details: One command generates the model, admin panel, views, policy, routes and locales for any resource — just like Rails scaffolding, but for your back-office.
@@ -47,10 +47,10 @@ Rendered by the [form builder](/reference/forms) helpers, under `Trek::Form::`:
47
47
 
48
48
  ## Content editor
49
49
 
50
- `Trek::Form::ContentEditorComponent` wraps the [Tiptap](https://tiptap.dev) editor and accepts three options — `nodes`, `blocks` and `floating` (all enabled by default) — to toggle the node toolbar, block formatting and floating menu:
50
+ `Trek::Form::ContentEditorComponent` wraps the [Tiptap](https://tiptap.dev) editor and accepts `nodes`, `blocks` and `floating` (all enabled by default) to toggle the text buttons, the block buttons and the floating menu, and `autofocus`:
51
51
 
52
52
  ```ruby
53
53
  f.content_editor :intro, nodes: false, floating: false
54
54
  ```
55
55
 
56
- Content is stored as ProseMirror JSON and rendered with [`formatted_content`](/reference/concerns/contentable). Image uploads (Uppy), link insertion and prompts are served by the [panel controllers](/reference/controllers).
56
+ Content is stored as ProseMirror JSON and rendered with [`formatted_content`](/reference/concerns/contentable). Image uploads (Uppy), link insertion and prompts are served by the [panel controllers](/reference/controllers). See the [Content editor](/content-editor) guide for its toolbar, how content is stored and rendered, and how to customize it.
@@ -1,14 +1,15 @@
1
1
  # Trek::Contentable
2
2
 
3
- Utilities for rich text stored as ProseMirror JSON in a `content` column — the format produced by Trek's [content editor](/reference/components#content-editor).
3
+ Utilities for content stored as ProseMirror JSON in a `content` column — the format produced by Trek's [content editor](/content-editor).
4
4
 
5
5
  ## Methods
6
6
 
7
7
  | Method | Returns |
8
8
  | --- | --- |
9
9
  | `parsed_content` | the content as a hash (parsing JSON strings if needed) |
10
- | `formatted_content` | safe HTML, rendered through the [ProseMirror pipeline](/reference/formatters) |
11
- | `content_text` | plain text extracted from all text nodes |
10
+ | `content_document` | the content as a `Prosemirror::Document`, to query or render it |
11
+ | `formatted_content` | safe HTML, rendered as described in [Rendering on the site](/content-editor#rendering-on-the-site) |
12
+ | `content_text` | the plain text of the content: blocks separated by a blank line, hard breaks by a newline |
12
13
  | `prosemirror_content?` | whether `content` is a valid ProseMirror document |
13
14
 
14
15
  ## Usage
@@ -22,7 +23,13 @@ page.formatted_content # => "<p>Hello <strong>world</strong></p>"
22
23
  page.content_text # => "Hello world"
23
24
  ```
24
25
 
26
+ Content in another column renders through the same schema: `Trek::Content::Document.parse(record, record.intro).to_html`. See the [Content editor](/content-editor) guide for the whole path, from the editor to the HTML.
27
+
28
+ ## Cleaning before saving
29
+
30
+ Before validation, empty paragraphs, empty list items and lists left empty are removed from the content, as rendering skips them (`Trek::Content::Cleaner`). The document stays one the editor opens: an empty document keeps one paragraph, a list item keeps the first paragraph it needs, and node types or attributes the schema doesn't know are kept. Content submitted as a JSON string, as the content editor sends it, is stored as a document. Translated content is cleaned in the current locale.
31
+
25
32
  ## Requirements
26
33
 
27
34
  - A `content` jsonb column
28
- - Used by [Page](/reference/models/page), [PageVersion](/reference/models/page-version) and [Fragment](/reference/models/fragment)
35
+ - Used by [Page](/reference/models/page) and [Fragment](/reference/models/fragment)
@@ -21,4 +21,4 @@ page.valid?
21
21
  page.title # => "Un titre : voici…"
22
22
  ```
23
23
 
24
- Works on plain strings **and** on ProseMirror documents (only `text` nodes are touched; the structure is preserved).
24
+ Works on plain strings **and** on ProseMirror documents (only `text` nodes are touched; the structure is preserved), including a document submitted by the content editor as a JSON string, which comes back as a Hash.
@@ -15,7 +15,7 @@ module Admin
15
15
  end
16
16
  ```
17
17
 
18
- - **Panel controllers** (`Trek::Panels::*`) — support endpoints used by the admin UI: image uploads (Uppy), link insertion and content editor prompts.
18
+ - **Panel controllers** (`Trek::Panels::*`) — support endpoints used by the admin UI: image uploads (Uppy), link insertion and content editor prompts. The installer generates their `Admin::Panels::*` subclasses in the app, which the admin routes point to: Trek's engine is isolated, so its own controllers only see the engine's routes, not the app's.
19
19
 
20
20
  ## Mixins
21
21
 
@@ -9,5 +9,6 @@
9
9
  | `APPSIGNAL_APP_ENV` | environment name reported to AppSignal (optional, defaults to `RAILS_ENV`) |
10
10
  | `DEEPL_AUTH_KEY` | automatic locale translation in the [scaffold generator](/reference/generators/scaffold) |
11
11
  | `FEATURE_AUDIT_LOG` | `false` stops the [audit log](/reference/generators/audit-log) recording requests (on by default) |
12
+ | `GOOD_JOB_MAX_THREADS` | number of job threads GoodJob runs, and the share of the database pool reserved for them (optional, defaults to `RAILS_MAX_THREADS`) — see [Background jobs](/background-jobs) |
12
13
  | `FEATURE_STORAGE` | `local` (development) or `s3` (production) |
13
14
  | `S3_BUCKET`, `S3_REGION`, `S3_ENDPOINT`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, `S3_BASE_URL` | S3 storage configuration for [uploads](/reference/uploaders) |
@@ -16,15 +16,10 @@ include Trek::Formattable
16
16
  format_attributes Trek::TypographyFormatter, :title
17
17
  ```
18
18
 
19
- ## ProseMirror → HTML pipeline
19
+ ## Rich text rendering
20
20
 
21
- `formatted_content` (from [Contentable](/reference/concerns/contentable)) renders ProseMirror JSON to safe HTML through the `prosemirror_to_html` gem, extended with:
21
+ `formatted_content` (from [Contentable](/reference/concerns/contentable)) renders the content editor's ProseMirror JSON to HTML with the [`prosemirror`](https://github.com/etaminstudio/prosemirror) gem, through `Trek::Content.schema`: HTML is escaped as it is built, attributes are typed, links and images only allow safe URLs, and links to pages are resolved. See [Rendering on the site](/content-editor#rendering-on-the-site) for what the HTML contains, and how invalid content is reported.
22
22
 
23
- | Piece | Role |
24
- | --- | --- |
25
- | `Nodes::ImageBlock` | renders `image_block` nodes as figures (Shrine image, alt, caption, size) |
26
- | `Nodes::PromptsBlock` | renders `prompts_block` nodes as call-to-action buttons |
27
- | `RemoveEmptyParagraphsFormatter` | strips empty `<p></p>` tags |
28
- | `GlobalIdToLinksFormatter` | resolves `gid://` references in links to real record URLs |
23
+ ### Custom blocks
29
24
 
30
- The pipeline is orchestrated by the `Prosemirror` model — extend it with your own node renderers when you add custom blocks to the editor.
25
+ Trek's node types (`Trek::Content::ImageBlock`, `PromptsBlock`…) can be subclassed to render the app's own components, and registered with `Trek::Content.schema = Trek::Content.default_schema.with(…)`: see [Customizing the rendering](/content-editor#customizing-the-rendering).
@@ -5,7 +5,7 @@ Trek ships `Trek::FormBuilder`, an extension of [`ViewComponent::Form`](https://
5
5
  | Helper | Renders |
6
6
  | --- | --- |
7
7
  | `f.group` | a label + input wrapper with errors |
8
- | `f.content_editor` | the Tiptap rich text editor |
8
+ | `f.content_editor` | the [content editor](/content-editor), based on Tiptap |
9
9
  | `f.image_field` | an image uploader with thumbnail preview (Uppy + Shrine) |
10
10
  | `f.sound_field` | an audio file uploader |
11
11
  | `f.switch_box` | a toggle switch |
@@ -1,7 +1,7 @@
1
1
  # Audit log
2
2
 
3
3
  ```sh
4
- rails g trek:install:audit_log
4
+ rails g trek:audit_log
5
5
  bin/rails db:migrate
6
6
  ```
7
7
 
@@ -108,6 +108,6 @@ The rows hold personal data: the author, the IP address, the user agent, and wha
108
108
 
109
109
  The `audit_logs` table uses the column names of the audit logs some apps wrote themselves (`actor`, `auditable`, `action`, `http_method`, `path`, `http_status`, `params`, `ip_address`, `user_agent`, `request_id`, `error_class`, `created_at`), so existing rows carry over. In such an app, skip the migration and replace the app's own files:
110
110
 
111
- 1. Run `rails g trek:install:audit_log`, delete the generated `db/migrate/*_trek_audit_logs.rb`, and let the generator overwrite the model, controller, views and policy.
111
+ 1. Run `rails g trek:audit_log`, delete the generated `db/migrate/*_trek_audit_logs.rb`, and let the generator overwrite the model, controller, views and policy.
112
112
  2. Delete the app's `Auditable` concern, its initializer and its purge job, and update the job's cron entry to `Trek::AuditLog::PurgeJob`.
113
113
  3. Move app-specific columns (e.g. a request duration, or a denormalized foreign key) to `audit_attributes`, and their scopes and associations to the `AuditLog` model.
@@ -15,6 +15,8 @@ Trek provides an install generator, that will:
15
15
  - create the relevant policies
16
16
  - generate and run the relevant migrations
17
17
 
18
+ It ends with what to do next: create an admin user, start the server, and the generators it leaves for later, to run as the app needs them: [`trek:scaffold`](/reference/generators/scaffold), [`trek:taxonomies`](/reference/generators/taxonomies), [`trek:audit_log`](/reference/generators/audit-log), [`trek:public_accounts`](/reference/generators/public-accounts) and [`trek:scalingo`](/deploy).
19
+
18
20
  ## Sub-generators
19
21
 
20
22
  The installer orchestrates dedicated sub-generators, all under the `trek:install:*` namespace. Each one can also be run individually, e.g. `rails g trek:install:healthcheck`.
@@ -32,12 +34,11 @@ The installer orchestrates dedicated sub-generators, all under the `trek:install
32
34
  | Tooling | esbuild, PostCSS, EditorConfig, Procfiles, Makefile, health check endpoint |
33
35
  | Linting | Standard, ESLint, Stylelint, Prettier, Slim Lint, Lefthook git hooks |
34
36
  | Security | Brakeman, bundler-audit, ruby_audit; HTTPS only (`force_ssl`, with HSTS), a Content Security Policy and the Permissions-Policy header (`trek:install:security_headers`) — see [Security headers](/reference/generators/security-headers) |
37
+ | Jobs | GoodJob as the Active Job backend, replacing Solid Queue — dashboard at `/admin/good_job`, cron in `config/initializers/good_job.rb`, pool sized by `GOOD_JOB_MAX_THREADS` — see [Background jobs](/background-jobs) |
35
38
  | Monitoring | AppSignal error tracking and performance monitoring — `config/appsignal.rb`, the push API key in the credentials, and the `AppsignalContext` concern tagging transactions per area and user |
36
39
  | Specs | RSpec, and specs for the models Trek installs (`trek:install:model_specs`): `spec/models/page_spec.rb` and `spec/models/user_spec.rb`, with their test data as [Oaken](https://github.com/kaspth/oaken) seed scripts — defaults in `db/seeds/setup/`, scenarios in `db/seeds/test/cases/` loaded with `seed "cases/…"`. They check Trek's behaviour in your app — slugs and paths, user validations and roles — so a customization that breaks it fails your suite; edit or remove the ones you deliberately change. Trek's own suite runs the same files |
37
40
  | N+1 detection | Prosopite (development/test), scanning every request — see [Controllers › N+1 detection](/reference/controllers#n-1-detection) |
38
41
  | CI | GitLab CI configuration: specs, linters, Brakeman, bundler-audit, and, commented out, a [Software Bill of Materials](#software-bill-of-materials) |
39
- | Deployment | Scalingo files (`trek:install:scalingo`, run on demand) — see [Deploying to Scalingo](/deploy) |
40
- | Audit log | The `AuditLog` model recording the admin's requests, and its admin list (`trek:install:audit_log`, run on demand) — see [Audit log](/reference/generators/audit-log) |
41
42
 
42
43
  ## ENV variables read by the installer
43
44
 
@@ -0,0 +1,141 @@
1
+ # Public accounts
2
+
3
+ ```sh
4
+ rails g trek:public_accounts Customer [--sign-in=code|password] [--api] [--path=customers] [--model-only]
5
+ bin/rails db:migrate
6
+ ```
7
+
8
+ Accounts for the people using the site or the mobile app (customers, members, readers…), apart from the admin's [`User`](/reference/models/user). They have their own model, table, sessions and sign-in, so nothing public can reach a staff account: signing up, deleting inactive accounts or merging duplicates only ever sees public accounts, and a public session never opens the admin.
9
+
10
+ The name is required, and is the app's own: `User` is the admin's account, so the generator refuses it, a namespaced name, and the names of Trek's models. Pick the word of the app's domain (`Customer`, `Member`, `Reader`…).
11
+
12
+ | Option | Effect |
13
+ | --- | --- |
14
+ | `--sign-in=code` (default) | Accounts sign in with a code emailed to them, which creates the account the first time: there is no password, nor sign-up form |
15
+ | `--sign-in=password` | Accounts sign up with an email and a password, confirm the email by a link, and reset a forgotten password by one: there are no codes |
16
+ | `--api` | A mobile app: JSON endpoints under `/api/v1`, and a session held through a JWT, with no pages. Without it, a website: pages, and a session kept in a cookie |
17
+ | `--path=customers` | Puts the routes under a path, e.g. `/customers/sign-in`: for an app with two kinds of public accounts |
18
+ | `--model-only` | Neither pages nor endpoints: see [Model only](#model-only). Can't be combined with `--api` or `--path` |
19
+
20
+ ## Model only
21
+
22
+ With `--model-only`, the generator adds the models, their migration, `Current.customer_session` and `Current.customer`, the mailer, its job for codes, the locales and the model specs, but no controllers, pages, routes nor JWT. It's for an app whose sign-in is its own, e.g. an API ported from another app that its mobile app already calls: the app keeps its endpoints and tokens, on top of `Customer` and its rules (passwords, lockout, sessions, inactive accounts).
23
+
24
+ The app then creates and finds the `Customer::Session` rows itself, or ignores them, and sets `Current.customer_session`. With passwords, the emailed links point at the app's domain (`https://<host>/account/confirm?token=…`, `/password-reset?token=…`, `/account/email?token=…`), or at `CUSTOMERS_APP_LINKS_URL`, as for the API: the app's own pages or mobile app handle them.
25
+
26
+ ## Signing in with an emailed code
27
+
28
+ 1. The person types their email; the app emails them a 6-digit code. It answers the same whether or not the email has an account (ANSSI guide on passwords, R14).
29
+ 2. They type the code: it signs them in to the email's account, created the first time. Signing up is signing in.
30
+
31
+ A code is valid for 10 minutes, for 5 tries (the right one included), and once. A new code replaces the earlier one. Only an HMAC of the code is stored, keyed on the app's `secret_key_base`, and the code is created in the job sending the email, so it's never in the job queue either. Change `validity` and `max_attempts` on `Customer::SignInCode`.
32
+
33
+ A new email address is confirmed the same way: a code sent to it.
34
+
35
+ ## Signing in with a password
36
+
37
+ - **Signing up** takes an email and a password, following the same rules as the admin's (`Trek::Users::PasswordPolicy`: 12 characters, a digit and a symbol below 20…, configurable), and signs in at once. A link confirming the email is sent, valid a day; following it sets `confirmed_at`. The app decides what an unconfirmed account may do (`customer.confirmed?`), and the account page sends the link again.
38
+ - **Failed sign-ins** lock signing in as for the admin (`Trek::Users::SignInLockout`), and `CustomerMailer#sign_in_locked` tells the account.
39
+ - **A forgotten password** is reset by a link, valid 15 minutes and used up by the new password (`has_secure_password`'s `password_reset_token`), which signs out every session. Asking for one answers the same whether or not the email has an account.
40
+ - **Changing the password** needs a recent sign-in (15 minutes, `Customer::Session::RECENT`), and signs out the other sessions.
41
+ - **A new email address** is kept in `unconfirmed_email` until the link sent to it, valid an hour, is followed.
42
+
43
+ ## Rate limits
44
+
45
+ Against guessing and flooding, each IP address may try to sign in 10 times in 3 minutes (5 with a password) and fail 20 times an hour, and ask for 10 emails (codes, links) in 15 minutes; each address gets at most 5 emails an hour. The limits are counted in `Rails.cache`, which must be shared between servers (see [Failed sign-ins](/reference/models/user#failed-sign-ins)).
46
+
47
+ ## Sessions
48
+
49
+ | | Website | API (`--api`) |
50
+ | --- | --- | --- |
51
+ | Held by | a signed `customer_session_id` cookie (`HttpOnly`, `SameSite=Lax`) | a JWT the app sends as `Authorization: Bearer …` |
52
+ | Expires | after 30 days without a request, and a year after signing in | the same, checked on the session row: the JWT only names it |
53
+ | Signing out | deletes the session and the cookie | deletes the session, and the JWT stops working |
54
+
55
+ Both are `Customer::Session` rows (`customer_sessions`), listed on the account, where the person can sign out the others. Change `idle_timeout` and `lifetime` on `Customer::Session` ([Trek::Users::SessionLifetime](/reference/models/user#sessions)). The JWT is signed with HS256 and a key derived from `secret_key_base`, and carries the session's id (`sub`) and the end of its lifetime (`exp`): unlike a self-contained token, it can be revoked.
56
+
57
+ Deleting the account, and changing the password, need a sign-in less than 15 minutes old; otherwise the website sends the person to sign in again, and the API answers 403 with `recent_sign_in_needed`.
58
+
59
+ Schedule the purge of expired sessions daily, as for the admin's: `Trek::PurgeExpiredSessionsJob.perform_later("Customer::Session")`.
60
+
61
+ The admin's own session (`session_id`, `User::Session`) is untouched: someone may be signed in to both, as two accounts that can share an email address.
62
+
63
+ ## What the generator adds
64
+
65
+ - `Customer` and `Customer::Session`, `Customer::SignInCode` for codes, and a migration creating their tables
66
+ - `Current.customer_session`, and `Current.customer`
67
+ - `Customers::Authentication`, and the controllers: under `Customers::` with pages for a website, under `Api::V1::Customers::` for the API
68
+ - `CustomerMailer` with its views in English and French, and `Customers::SignInCodeJob` for codes
69
+ - `config/locales/customers.{en,fr}.yml`
70
+ - the routes, on paths of their own (below), so renaming the model keeps them
71
+ - specs, when the app has a `spec` directory
72
+
73
+ ### Website
74
+
75
+ `Customers::Authentication` is included in `ApplicationController`, so every page may use:
76
+
77
+ | Helper | Returns |
78
+ | --- | --- |
79
+ | `current_customer`, `customer_signed_in?` | the signed-in customer, if any |
80
+ | `staff_user` | the admin's user signed in in this browser, when privileged, for previews and links to the admin on the site. Read only: it neither extends nor ends their admin session, and never signs a customer in |
81
+
82
+ A page for customers only calls `before_action :require_customer`, which sends the others to sign in and brings them back after.
83
+
84
+ | Path | Page |
85
+ | --- | --- |
86
+ | `GET /sign-in` | the sign-in form (`customer_sign_in_path`): the email for a code, or the email and password |
87
+ | `GET /sign-in/code` | the code form (codes) |
88
+ | `GET /sign-up` | the sign-up form (passwords) |
89
+ | `GET /password-reset/new` | asking for a link to choose a new password (passwords) |
90
+ | `GET /account/confirm?token=…` | the link confirming the email (passwords) |
91
+ | `DELETE /sign-out` | signs out |
92
+ | `GET /account` | the account: name, email, password, signed-in browsers, deletion (`customer_account_path`) |
93
+ | `GET /account/email/new` | changing the email, confirmed by a code or a link sent to the new address |
94
+ | `GET /account/password/edit` | changing the password (passwords) |
95
+
96
+ The pages render in the site's layout, unstyled, with their notices in `app/views/customers/_flash.html.slim`: move those to the layout if it shows flash messages.
97
+
98
+ ### API
99
+
100
+ The endpoints are the API's first version, under `/api/v1`, so that a later version can be served next to them while older releases of the mobile app still call these. Every endpoint answers JSON; an error comes as `{ "error": "invalid_code", "message": "…" }`, the message in the request's locale.
101
+
102
+ | Endpoint | Body | Answer |
103
+ | --- | --- | --- |
104
+ | `POST /api/v1/sign-in` | codes: `email`; passwords: `email`, `password` | codes: 202, a code is emailed; passwords: 201, `{ token, customer }` |
105
+ | `POST /api/v1/sign-in/code` | `email`, `otp` | 201, `{ token, customer }` (codes) |
106
+ | `POST /api/v1/sign-up` | `email`, `password`, `name` | 201, `{ token, customer }` (passwords) |
107
+ | `POST /api/v1/password-reset` | `email` | 202, a link is emailed if the email has an account (passwords) |
108
+ | `PATCH /api/v1/password-reset` | `token`, `password` | 204 (passwords) |
109
+ | `POST`, `PATCH /api/v1/account/confirmation` | `token` for `PATCH` | sends the confirmation link again; confirms the email (passwords) |
110
+ | `DELETE /api/v1/session` | | 204, signs out |
111
+ | `GET`, `PATCH`, `DELETE /api/v1/account` | `name` | the account; deleting needs a recent sign-in |
112
+ | `POST /api/v1/account/email` | `email` | 202, a code or a link is emailed to the new address |
113
+ | `PATCH /api/v1/account/email` | codes: `email`, `otp`; passwords: `token` | the account, with its new email; 409 when another account has it |
114
+ | `PATCH /api/v1/account/password` | `password` | 204 (passwords); needs a recent sign-in |
115
+ | `GET /api/v1/account/sessions` | | the signed-in devices, `current` for this one |
116
+ | `DELETE /api/v1/account/sessions/:id`, `/others` | | 204 |
117
+
118
+ With passwords, the emailed links point at the app's domain (`https://<host>/account/confirm?token=…`, `/password-reset?token=…`, `/account/email?token=…`), or at `CUSTOMERS_APP_LINKS_URL`: the mobile app opens them (iOS universal links, Android app links) and sends their `token` to the endpoints above.
119
+
120
+ ## Audit log
121
+
122
+ When the app has the [audit log](/reference/generators/audit-log), the account controllers write to it too: sign-ins, failed or not, sign-ups, code and link requests (with no actor), and account changes, the customer being the actor.
123
+
124
+ ## Inactive accounts
125
+
126
+ `Customer.inactive_since(time)` lists the accounts with no request since `time` (`last_activity_at`, written at most every 5 minutes), e.g. for a job deleting them. It can only ever list customers.
127
+
128
+ ## Upgrading Trek
129
+
130
+ The generated files are the app's own: upgrading Trek never changes them. On each upgrade, check:
131
+
132
+ - **The CHANGELOG,** for entries on what the generated code relies on in the gem: `Trek::Users::SessionLifetime`, `Trek::Users::SignInCode` (codes), `Trek::Users::SignInLockout` and `Trek::Users::PasswordPolicy` (passwords), `Trek::PurgeExpiredSessionsJob`, `Trek::ResolveSessionHostnameJob` and `Trek::Auditable`.
133
+ - **The generator's own changes,** a security fix among them, which reach the app only by running it again. On a clean working tree, run it with the same name and options, then review `git diff` and restore the app's own changes:
134
+
135
+ ```sh
136
+ rails g trek:public_accounts Customer --force # plus the options it was generated with
137
+ git diff
138
+ ```
139
+
140
+ Running it again adds nothing already there: no second migration, route or `Current` attribute.
141
+ - **The admin's session,** which `staff_user` reads: its `session_id` cookie and `User::Session`, in `Customers::Authentication#staff_user`. An upgrade note says when they change.
@@ -41,7 +41,7 @@ The policy only **reports** violations at first (`config.content_security_policy
41
41
 
42
42
  ### Violation reports
43
43
 
44
- Browsers send each violation to the policy's `report-uri`: `/csp-reports`, which `Trek::CspReportsController` answers (the generator adds `post "csp-reports"` to the routes). It reports each violation to **AppSignal**, when the app uses it, in a `csp` namespace: one incident per directive and blocked origin (e.g. `script-src-elem https://cdn.example.net`), tagged with the page and whether the policy was enforced, so a new violation is notified once and closed once fixed. It logs each one too (`[CSP] script-src-elem blocked https://cdn.example.net on /pages/team (report)`), which is all an app without AppSignal gets.
44
+ Browsers send each violation to the policy's `report-uri`: `/csp-reports`, which `Trek::CspReportsController` answers (the generator adds `post "csp-reports"` to the routes). It reports each violation to **AppSignal**, when the app uses it, in a `csp` namespace: one incident per directive and blocked origin (e.g. `script-src-elem https://cdn.example.net`), tagged with the page and whether the policy was enforced, so a new violation is notified once and closed once fixed. To tell what was blocked, each report is also tagged with the browser's user agent and, when the browser gives them, where it happened (`source`: the file's URL, without its query, and the line) and the `sample`: the first 40 characters of an inline script, which the policy asks for with `'report-sample'` (`policy.script_src :self, :report_sample`). Tags are cut to 255 characters, as AppSignal drops longer ones. It logs each one too (`[CSP] script-src-elem blocked inline on /pages/team (report) at https://www.example.com/pages/team:12: "alert(1)"`), which is all an app without AppSignal gets.
45
45
 
46
46
  It keeps the reports about the app's own pages only, and drops what browser extensions load or inject, which makes most reports and says nothing about the app. It keeps the page's path, not its query, which may carry a token, and the blocked resource's origin, not its URL. Browsers send no CSRF token nor cookie: the endpoint needs neither, and answers `204`.
47
47
 
@@ -8,7 +8,8 @@ A comprehensive list of features and settings included in Trek.
8
8
  - [Admin user](/reference/generators/admin-user) — `rails g trek:admin:user`
9
9
  - [Scaffold](/reference/generators/scaffold) — `rails g trek:scaffold`
10
10
  - [Taxonomies](/reference/generators/taxonomies) — `rails g trek:taxonomies`
11
- - [Audit log](/reference/generators/audit-log) — `rails g trek:install:audit_log`
11
+ - [Audit log](/reference/generators/audit-log) — `rails g trek:audit_log`
12
+ - [Public accounts](/reference/generators/public-accounts) — `rails g trek:public_accounts`
12
13
  - [Security headers](/reference/generators/security-headers) — `rails g trek:install:security_headers`
13
14
 
14
15
  ## Models
@@ -16,6 +16,7 @@ Reusable chunks of content — a footer text, a hero tagline, a contact blurb
16
16
 
17
17
  - Includes [Contentable](/reference/concerns/contentable), [Translatable](/reference/concerns/translatable) (`title`, `content`), [Keyable](/reference/concerns/keyable) and `strip_attributes`
18
18
  - `acts_as_list scope: [:namespace]` with an `ordered` scope
19
+ - A `search(query)` scope, case-insensitive, matching the key (`namespace.key`), the title or the text of the content in the current locale. The admin's fragments index searches with it.
19
20
  - `to_s` returns `"namespace.key"`
20
21
 
21
22
  ## Usage