trek 0.1.21 → 0.1.22

data/docs/reference/concerns/fragmentable.md

@@ -0,0 +1,33 @@
+# Trek::Fragmentable
+
+Composes a record from reusable [fragments](/reference/models/fragment), based on a configuration matrix mapping record keys to fragment ids.
+
+## Configuration
+
+```yaml
+# page_fragments configuration
+page_fragments:
+  matrix:
+    home: [1, 2, 3]
+    about: [4, 5]
+```
+
+## Methods
+
+| Method | Purpose |
+| --- | --- |
+| `fragments` | the Fragment records configured for this record's `key` |
+| `fragments_attributes=` | bulk-updates fragments from nested form attributes |
+
+## Usage
+
+```ruby
+class Page < ApplicationRecord
+  include Trek::Fragmentable
+end
+
+page = Page.find_by(key: "home")
+page.fragments # => [Fragment(1), Fragment(2), Fragment(3)]
+```
+
+This is what powers the fragment editing UI on page forms in the admin.

data/docs/reference/concerns/keyable.md

@@ -0,0 +1,18 @@
+# Trek::Keyable
+
+Batch lookup of records by their `key` attribute, preserving the requested order.
+
+## Methods
+
+| Method | Returns |
+| --- | --- |
+| `Model.take_by_keys(keys)` | the records matching `keys`, **in the same order**, with `nil` for missing keys |
+
+## Usage
+
+```ruby
+Page.take_by_keys(%w[services about missing])
+# => [#<Page key="services">, #<Page key="about">, nil]
+```
+
+Handy for rendering a fixed set of pages or fragments in a specific order in your views.

data/docs/reference/concerns/orderable.md

@@ -0,0 +1,26 @@
+# Trek::Orderable
+
+Position tracking with [acts_as_list](https://github.com/brendon/acts_as_list), scoped by parent.
+
+## What it adds
+
+- `acts_as_list scope: :parent, top_of_list: 0`
+- An `ordered` scope (position order)
+- All the `acts_as_list` instance methods: `insert_at`, `move_to_top`, `move_to_bottom`, `move_higher`, `move_lower`…
+
+## Requirements
+
+- A `position` integer column (and a `parent_id` column for the scope)
+
+## Usage
+
+```ruby
+class MenuNode < ApplicationRecord
+  include Trek::Orderable
+end
+
+MenuNode.where(parent: menu).ordered
+node.move_to_top
+```
+
+This is what powers drag & drop reordering (SortableJS) in the admin lists.

data/docs/reference/concerns/pageable.md

@@ -0,0 +1,35 @@
+# Trek::Pageable
+
+The bridge between your content models (articles, products…) and their [Page](/reference/models/page) representation. The model owns the data; the page owns the title, slug, SEO and position.
+
+## What it adds
+
+- `has_one :page, as: :pageable, dependent: :destroy, autosave: true` with `accepts_nested_attributes_for :page`
+- Delegates `title`, `image`, `image_url`, `current_image`, `current_image_url`, `to_s` to the page
+- `before_create` guarantees the page exists
+- `to_param` uses the page slug on the public site (and the id in the admin)
+
+## Class macros
+
+| Macro | Purpose |
+| --- | --- |
+| `has_position_from_page` | delegates `position` to the page and adds a `by_position` scope |
+| `has_root_scope` | adds a `root` scope finding resources under their index page |
+| `find_with_page_slug(slug)` | class method — resource lookup by page slug |
+
+## Navigation helpers
+
+`parent?`, `parent`, `children?`, `children` — traverse the page hierarchy from the resource side.
+
+## Usage
+
+```ruby
+class Article < ApplicationRecord
+  include Trek::Pageable
+  has_position_from_page
+end
+
+article = Article.create(page_attributes: { title: "My Article" })
+article.title      # => "My Article" (delegated)
+article.to_param   # => "my-article"
+```

data/docs/reference/concerns/pathable.md

@@ -0,0 +1,28 @@
+# Trek::Pages::Pathable
+
+Manages a page's URL paths across locales: the current path, the full history (for redirects), and automatic regeneration when pages move in the tree.
+
+## What it adds
+
+- `belongs_to :current_path` and `has_many :paths` → [PagePath](/reference/models/page-path)
+- `after_save_commit`, paths are (re)created for the page **and all its descendants**
+
+## Methods
+
+| Method | Returns |
+| --- | --- |
+| `Page.find_at_full_path(path)` | the page at this path (raises `ActiveRecord::RecordNotFound`) |
+| `full_path` | the current path string |
+| `full_path_from_tree` | the path computed from ancestor slugs |
+
+## Usage
+
+```ruby
+parent = Page.create(title: "Services")
+child = Page.create(title: "Design", parent: parent)
+
+child.full_path                          # => "services/design"
+Page.find_at_full_path("services/design") # => child
+```
+
+Old paths remain in `page.paths`, which lets your front-end controllers redirect outdated URLs to `full_path`.

data/docs/reference/concerns/phonable.md

@@ -0,0 +1,28 @@
+# Trek::Phonable
+
+Phone number validation, normalization and formatting, backed by [Phonelib](https://github.com/daddyz/phonelib).
+
+## API
+
+```ruby
+class Organization < ApplicationRecord
+  include Trek::Phonable
+  phonable_attributes :phone, :fax
+end
+```
+
+For each declared attribute:
+
+- a validation (`phone: { possible: true, allow_blank: true }`)
+- normalization to E.164 international format on save
+- `formatted_{attr}` — national format (`"01 23 45 67 89"`)
+- `{attr}_with_country_code` — E.164 (`"+33123456789"`)
+
+## Usage
+
+```ruby
+org = Organization.create(phone: "0123456789")
+org.phone                   # => "+33123456789"
+org.formatted_phone         # => "01 23 45 67 89"
+org.phone_with_country_code # => "+33123456789"
+```

data/docs/reference/concerns/search-engine-optimizable.md

@@ -0,0 +1,19 @@
+# Trek::Pages::SearchEngineOptimizable
+
+SEO metadata with sensible fallbacks: explicit title/description/image when set, model defaults otherwise (including the parent page's image).
+
+## Methods
+
+| Method | Returns |
+| --- | --- |
+| `seo_values` | `{ title:, description:, image:, slug: }` with fallbacks applied |
+| `meta_tags` | `seo_values` without the slug — ready for your `<head>` |
+| `default_title` / `default_description` / `default_image` | the fallback values |
+
+## Usage
+
+```slim
+/ app/views/layouts/application.html.slim
+- @page.meta_tags.each do |name, content|
+  meta name=name content=content
+```

data/docs/reference/concerns/searchable.md

@@ -0,0 +1,22 @@
+# Trek::Searchable
+
+Accent-insensitive full-text search on a record's page title, using PostgreSQL's `unaccent` extension.
+
+## What it adds
+
+- A `search(query)` scope — joins to the associated page and matches the title with an unaccented `ILIKE`; returns everything when the query is blank
+
+## Usage
+
+```ruby
+class Article < ApplicationRecord
+  include Trek::Pageable
+  include Trek::Searchable
+end
+
+Article.search("élève") # matches "eleve", "Élève"…
+```
+
+## Controller side
+
+The `Trek::Search` controller concern wires this into index actions: it filters `@objects` by `params[:search]` whenever the model responds to `search` — that's what powers the search field in admin lists.

data/docs/reference/concerns/sectionable.md

@@ -0,0 +1,24 @@
+# Trek::Sectionable
+
+Organizes a record's content into ordered, typed sections (hero, features, testimonials…).
+
+## What it adds
+
+- `has_many :sections, -> { ordered }, as: :sectionable, dependent: :destroy`
+- `sections_instances` — the unwrapped section objects, in order
+
+## Usage
+
+```ruby
+class Page < ApplicationRecord
+  include Trek::Sectionable
+
+  SECTIONS = [HeroSection, FeaturesSection].freeze
+end
+
+page.sections_instances.each do |section|
+  render section_component_for(section)
+end
+```
+
+Sections are opt-in per page via the `sectioned` boolean column. The including class defines the allowed section types through the `SECTIONS` constant.

data/docs/reference/concerns/sluggable.md

@@ -0,0 +1,21 @@
+# Trek::Sluggable
+
+Auto-generates locale-aware URL slugs before validation, for every available locale.
+
+## Behavior
+
+- `before_validation`, the slug is regenerated per locale: from a route translation of the page `key` when one exists, otherwise by parameterizing the SEO title
+- Validates slug presence (except for the root page) and uniqueness among siblings (`scope: :parent_id`)
+
+## Requirements
+
+- [Translatable](/reference/concerns/translatable) with a translated `slug`
+- A `key` attribute, a `root?` predicate and `seo_values` (provided by [SearchEngineOptimizable](/reference/concerns/search-engine-optimizable))
+
+## Usage
+
+```ruby
+page = Page.new(key: "services", title: "Our Services")
+page.save
+page.slug # => "our-services"
+```

data/docs/reference/concerns/taggable.md

@@ -0,0 +1,20 @@
+# Trek::Taggable
+
+Tag associations for any model, via the [taxonomy models](/reference/models/tag) (installed by the [taxonomies generator](/reference/generators/taxonomies)).
+
+## What it adds
+
+- `has_many :taggings, as: :taggable, dependent: :destroy`
+- `has_many :tags, through: :taggings`
+- `tag_names` — the tag names as an array of strings
+
+## Usage
+
+```ruby
+class Article < ApplicationRecord
+  include Trek::Taggable
+end
+
+article.tags << Tag.find_or_create_by(name: "Ruby", key: "ruby")
+article.tag_names # => ["Ruby"]
+```

data/docs/reference/concerns/translatable.md

@@ -0,0 +1,35 @@
+# Trek::Translatable
+
+Multi-language attributes, backed by [Mobility](https://github.com/shioyama/mobility). Translated values are stored in `jsonb` columns keyed by locale.
+
+## API
+
+```ruby
+class Page < ApplicationRecord
+  include Trek::Translatable
+  translate_attributes :title, :description
+end
+```
+
+`translate_attributes(*attr_names)` declares the translatable attributes (it delegates to Mobility's `translates`).
+
+## Usage
+
+```ruby
+page = Page.create(title: "Home")
+I18n.with_locale(:fr) { page.update(title: "Accueil") }
+
+page.title                              # => "Home" (current locale)
+I18n.with_locale(:fr) { page.title }    # => "Accueil"
+```
+
+Stored as:
+
+```json
+{ "en": "Home", "fr": "Accueil" }
+```
+
+## Requirements
+
+- A `jsonb` column per translated attribute (default `{}`)
+- Used by [Page](/reference/models/page), [PagePath](/reference/models/page-path), [Fragment](/reference/models/fragment) and [MenuNode](/reference/models/menu-node)

data/docs/reference/concerns/versionable.md

@@ -0,0 +1,27 @@
+# Trek::Pages::Versionable
+
+Content versioning for [pages](/reference/models/page): snapshot the current content and image as a [PageVersion](/reference/models/page-version), then keep editing while the snapshot stays live.
+
+## What it adds
+
+- `has_many :versions` (most recent first) with a `current` sub-scope, plus `accepts_nested_attributes_for :versions`
+
+## Methods
+
+| Method | Purpose |
+| --- | --- |
+| `create_current_version_from_page!` | snapshots the page's `content` and `image` as the new current version |
+| `current_version` | the live version (or `nil` when not versioned) |
+| `current_content` / `current_sections` | content from the current version, falling back to the page itself |
+| `current_image` / `current_image_url` | image from the current version, falling back to the page, then its parent |
+
+## Usage
+
+Versioning is opt-in per page via the `versioned` boolean column:
+
+```ruby
+page.update(versioned: true)
+page.create_current_version_from_page!  # freeze what's live
+page.update(content: new_draft)         # keep editing safely
+page.current_content                    # => still the frozen snapshot
+```

data/docs/reference/controllers.md

@@ -0,0 +1,23 @@
+# Controllers
+
+- **`Trek::BaseController`** — the base for all admin controllers: authentication, authorization, localization, the `admin` layout and Trek's [form builder](/reference/forms).
+- **`Trek::ResourceController`** — extends `BaseController` with the full CRUD (`index`, `show`, `new`, `create`, `edit`, `update`, `destroy`), wired to ActionPolicy (`authorized_scope`, `authorize!`) and ordering. Scaffolded controllers inherit from it and only need to declare their `model`:
+
+```ruby
+module Admin
+  class BooksController < Trek::ResourceController
+    private
+
+    def model
+      Book
+    end
+  end
+end
+```
+
+- **Panel controllers** (`Trek::Panels::*`) — support endpoints used by the admin UI: image uploads (Uppy), link insertion and content editor prompts.
+
+## Mixins
+
+- `include Trek::Pagination` — paginates the index with Kaminari
+- `include Trek::Search` — filters the index by `params[:search]` when the model is [Searchable](/reference/concerns/searchable)

data/docs/reference/environment-variables.md

@@ -0,0 +1,9 @@
+# Environment variables
+
+| Variable | Purpose |
+| --- | --- |
+| `ADMIN_EMAIL` / `ADMIN_PASSWORD` | credentials used by [`trek:admin:user`](/reference/generators/admin-user) |
+| `POSTMARK_API_TOKEN` | Postmark email delivery (auto-injected into credentials by the [installer](/reference/generators/install)) |
+| `DEEPL_AUTH_KEY` | automatic locale translation in the [scaffold generator](/reference/generators/scaffold) |
+| `FEATURE_STORAGE` | `local` (development) or `s3` (production) |
+| `S3_BUCKET`, `S3_REGION`, `S3_ENDPOINT`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, `S3_BASE_URL` | S3 storage configuration for [uploads](/reference/uploaders) |

data/docs/reference/formatters.md

@@ -0,0 +1,30 @@
+# Formatters
+
+## TypographyFormatter
+
+`Trek::TypographyFormatter` applies French typography rules to strings **and** ProseMirror documents (only `text` nodes are modified):
+
+- non-breaking spaces before `: ; ! ? % € $ »` and after `«`, dashes, `n°`
+- non-breaking spaces before units (km, kg, h, min, °C…) and between digit groups
+- `...` → `…`, ASCII apostrophes → typographic `'`
+- removes double spaces and spaces before periods/commas
+
+Wire it to attributes with [Formattable](/reference/concerns/formattable):
+
+```ruby
+include Trek::Formattable
+format_attributes Trek::TypographyFormatter, :title
+```
+
+## ProseMirror → HTML pipeline
+
+`formatted_content` (from [Contentable](/reference/concerns/contentable)) renders ProseMirror JSON to safe HTML through the `prosemirror_to_html` gem, extended with:
+
+| Piece | Role |
+| --- | --- |
+| `Nodes::ImageBlock` | renders `image_block` nodes as figures (Shrine image, alt, caption, size) |
+| `Nodes::PromptsBlock` | renders `prompts_block` nodes as call-to-action buttons |
+| `RemoveEmptyParagraphsFormatter` | strips empty `<p></p>` tags |
+| `GlobalIdToLinksFormatter` | resolves `gid://` references in links to real record URLs |
+
+The pipeline is orchestrated by the `Prosemirror` model — extend it with your own node renderers when you add custom blocks to the editor.

data/docs/reference/forms.md

@@ -0,0 +1,21 @@
+# Forms
+
+Trek ships `Trek::FormBuilder`, an extension of [`ViewComponent::Form`](https://github.com/pantographe/view_component-form)'s builder, automatically used in admin views. On top of the standard helpers, it provides:
+
+| Helper | Renders |
+| --- | --- |
+| `f.group` | a label + input wrapper with errors |
+| `f.content_editor` | the Tiptap rich text editor |
+| `f.image_field` | an image uploader with thumbnail preview (Uppy + Shrine) |
+| `f.sound_field` | an audio file uploader |
+| `f.switch_box` | a toggle switch |
+| `f.link_select` | a link picker (internal pages & external links) |
+
+Each helper renders the matching component from the [`Trek::Form` namespace](/reference/components#form-components).
+
+```slim
+= form_with model: [:admin, @book] do |f|
+  = f.group :title
+  = f.content_editor :intro, floating: false
+  = f.switch_box :published
+```

data/docs/reference/generators/admin-user.md

@@ -0,0 +1,17 @@
+# Admin user
+
+```sh
+rails g trek:admin:user
+# or (soon)
+trek admin:user
+```
+
+Creates an admin user with the credentials defined by the `ADMIN_EMAIL` and `ADMIN_PASSWORD` ENV variables, typically set in `.env`:
+
+```sh
+# .env
+ADMIN_EMAIL=admin@example.com
+ADMIN_PASSWORD=a-strong-password
+```
+
+The created user gets the `admin` [role](/reference/models/user#roles), which makes it `privileged?` and grants it full access in the default [policies](/reference/policies).

data/docs/reference/generators/install.md

@@ -0,0 +1,42 @@
+# Installer
+
+```sh
+rails g trek:install
+# or (soon)
+trek install
+```
+
+Trek provides an install generator, that will:
+
+- install all dependencies
+- create the `User` model and include Trek's concerns
+- create the `Page`, `PagePath` and `PageVersion` models and include Trek's concerns
+- create the `Fragment` model and include Trek's concerns
+- create the relevant policies
+- generate and run the relevant migrations
+
+## Sub-generators
+
+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`.
+
+| Area | What gets set up |
+| --- | --- |
+| Authentication | Sorcery, the `UserSession` form model, login/logout & password reset panels |
+| Authorization | ActionPolicy and the base policies |
+| Models | `User`, `Page`, `PagePath`, `PageVersion`, `Fragment`, `MenuNode`, `ExternalLink`, `Current` — with migrations |
+| Attachments | Shrine configuration and the uploaders |
+| Emails | Postmark and the user mailer |
+| I18n | rails-i18n, Mobility, i18n-tasks and the locale files |
+| Admin panels | Pages, fragments, users, sessions, password resets, routes, dashboard |
+| Pagination | Kaminari |
+| Tooling | esbuild, PostCSS, EditorConfig, Procfiles, Makefile, health check endpoint |
+| Linting | Standard, ESLint, Stylelint, Prettier, Slim Lint, Lefthook git hooks |
+| Security | Brakeman, bundler-audit, ruby_audit |
+| CI | GitLab CI configuration |
+
+## ENV variables read by the installer
+
+Define these **before** running the installer to have them injected automatically:
+
+- `POSTMARK_API_TOKEN` — injected into the Rails credentials for email delivery
+- `DEEPL_AUTH_KEY` — enables automatic locale translation in the [scaffold generator](/reference/generators/scaffold)

data/docs/reference/generators/scaffold.md

@@ -0,0 +1,37 @@
+# Scaffold
+
+```sh
+rails g trek:scaffold Book title intro:text
+```
+
+Akin to Rails', Trek's scaffold generates, with a single command:
+
+- the `Book` model and migration (calling the Rails `model` generator behind the scenes)
+- the `Admin::BooksController`, inheriting from [`Trek::ResourceController`](/reference/controllers)
+- the Slim views: `index`, `show`, `new`, `edit` and the `_form` partial
+- the `Admin::BookPolicy`, inheriting from [`Trek::ResourcePolicy`](/reference/policies)
+- the `resources :books` route in the `admin` namespace
+- the locale files for the model and its admin panel, in every configured locale (auto-translated via DeepL when `DEEPL_AUTH_KEY` is set)
+- the entry in the admin dashboard menu
+
+## Field types
+
+Standard Rails attribute types are supported (`string`, `text`, `integer`, `float`, `decimal`, `boolean`, `date`, `datetime`, `references`…) and mapped to the matching [form helpers](/reference/forms): `text` renders the content editor, `boolean` a switch box, `references` a collection select, and so on.
+
+## Opt-in concerns
+
+The generated model ships with commented-out hooks for Trek's most useful [concerns](/reference/), ready to be enabled when needed:
+
+```ruby
+class Book < ApplicationRecord
+  # include Trek::Formattable
+  # format_attributes Trek::TypographyFormatter, :title
+
+  # include Trek::Translatable
+  # translate_attributes :title
+
+  # include RecordImageUploader::Attachment(:image)
+
+  strip_attributes
+end
+```

data/docs/reference/generators/taxonomies.md

@@ -0,0 +1,21 @@
+# Taxonomies
+
+```sh
+rails g trek:taxonomies
+```
+
+Sets up a tagging & categorization system:
+
+- the [`Tag`, `TagCategory` and `Tagging` models](/reference/models/tag) with their migrations
+- the admin panel to manage tags and categories
+
+Once installed, make any model taggable with the [`Trek::Taggable`](/reference/concerns/taggable) concern:
+
+```ruby
+class Article < ApplicationRecord
+  include Trek::Taggable
+end
+
+article.tags << Tag.find_or_create_by(name: "Ruby")
+article.tag_names # => ["Ruby"]
+```

data/docs/reference/icons.md

@@ -0,0 +1,11 @@
+# Icons
+
+Trek bundles ~40 SVG icons, rendered with `Trek::IconComponent`:
+
+```ruby
+render Trek::IconComponent.new(:search)
+```
+
+Available keys include: `add`, `arrow-bar-left`, `arrow-bar-right`, `bold`, `check`, `chevron-left`, `chevron-right`, `chevron-double`, `close`, `cursor`, `danger`, `download`, `eraser`, `eye`, `grid`, `hr`, `italic`, `layout`, `link`, `list`, `logout`, `paragraph`, `pic`, `profile`, `quotation`, `rating`, `redo`, `undo`, `search`…
+
+[MenuNode](/reference/models/menu-node) records can reference an icon via their `icon_key` to display it in the admin sidebar.

data/docs/reference/index.md

@@ -0,0 +1,47 @@
+# Reference manual
+
+A comprehensive list of features and settings included in Trek.
+
+## Generators
+
+- [Installer](/reference/generators/install) — `rails g trek:install`
+- [Admin user](/reference/generators/admin-user) — `rails g trek:admin:user`
+- [Scaffold](/reference/generators/scaffold) — `rails g trek:scaffold`
+- [Taxonomies](/reference/generators/taxonomies) — `rails g trek:taxonomies`
+
+## Models
+
+Generated into your application — they're yours to read and modify.
+
+- [Page](/reference/models/page), [PageVersion](/reference/models/page-version), [PagePath](/reference/models/page-path)
+- [Fragment](/reference/models/fragment)
+- [MenuNode](/reference/models/menu-node), [ExternalLink](/reference/models/external-link)
+- [User](/reference/models/user) (and its session & password-reset form models)
+- [Tag, TagCategory & Tagging](/reference/models/tag) (with the taxonomies generator)
+- [Current](/reference/models/current)
+
+## Concerns
+
+Trek's behaviors, packaged as concerns you can mix into any model:
+
+- Content: [Contentable](/reference/concerns/contentable), [Fragmentable](/reference/concerns/fragmentable), [Sectionable](/reference/concerns/sectionable), [Formattable](/reference/concerns/formattable)
+- I18n & URLs: [Translatable](/reference/concerns/translatable), [Sluggable](/reference/concerns/sluggable), [Pathable](/reference/concerns/pathable)
+- Pages: [Pageable](/reference/concerns/pageable), [Versionable](/reference/concerns/versionable), [SearchEngineOptimizable](/reference/concerns/search-engine-optimizable)
+- Utilities: [Orderable](/reference/concerns/orderable), [Keyable](/reference/concerns/keyable), [Searchable](/reference/concerns/searchable), [Taggable](/reference/concerns/taggable), [Phonable](/reference/concerns/phonable)
+
+## Back-office
+
+- [Controllers](/reference/controllers) — `Trek::BaseController`, `Trek::ResourceController`, panels
+- [Forms](/reference/forms) — `Trek::FormBuilder` and its custom helpers
+- [Formatters](/reference/formatters) — typography & ProseMirror-to-HTML pipeline
+- [Policies](/reference/policies) — ActionPolicy integration
+- [Uploaders](/reference/uploaders) — Shrine-based attachments
+
+## Front-end
+
+- [Components](/reference/components) — the ViewComponents powering the admin UI
+- [Icons](/reference/icons) — the bundled SVG icon set
+
+## Configuration
+
+- [Environment variables](/reference/environment-variables)

data/docs/reference/models/current.md

@@ -0,0 +1,11 @@
+# Current
+
+Request-scoped global context, built on `ActiveSupport::CurrentAttributes` and generated into `app/models/current.rb`.
+
+Trek uses it to cache per-request data — for instance the loaded icon set:
+
+```ruby
+Current.icons
+```
+
+Extend it with your own request-scoped attributes as your application grows (current user, tenant, locale…).

data/docs/reference/models/external-link.md

@@ -0,0 +1,16 @@
+# ExternalLink
+
+Links pointing outside your application, usable in [menus](/reference/models/menu-node) and content.
+
+## Columns
+
+| Column | Type | Notes |
+| --- | --- | --- |
+| `key` | string | unique, optional |
+| `url` | string | required |
+
+## Behavior
+
+- `has_many :menu_nodes, as: :linkable, dependent: :destroy`
+- `key` uniqueness (allow nil), `url` presence
+- `to_s` returns the URL