trek 0.1.20 → 0.1.22

data/app/components/trek/form/image_field_component/image_field_component.js

@@ -8,7 +8,13 @@ import French from "@uppy/locales/lib/fr_FR";
 import "@uppy/core/dist/style.css";
 
 export class Controller extends BaseController {
-  static targets = ["content", "fileInput", "hiddenInput", "preview"];
+  static targets = [
+    "content",
+    "fileInput",
+    "hiddenInput",
+    "preview",
+    "removeInput",
+  ];
 
   connect() {
     this.uppy = new Uppy({
@@ -48,6 +54,9 @@ export class Controller extends BaseController {
       const uploadedFileData = response.body["data"];
 
       this.hiddenInputTarget.value = JSON.stringify(uploadedFileData);
+
+      // Clear the remove flag when a new file is uploaded
+      this.removeInputTarget.value = "";
     });
 
     this.uppy.on("file-removed", () => {
@@ -64,6 +73,19 @@ export class Controller extends BaseController {
     this.uppy = null;
   }
 
+  removeImage() {
+    // Clear the cached upload data
+    this.hiddenInputTarget.value = "";
+
+    // Set the remove flag so Shrine deletes the attachment on save
+    this.removeInputTarget.value = "1";
+
+    // Reset preview to placeholder icon
+    this.previewTarget.innerHTML = `<svg class="c-trek--icon-root c-trek--icon-trek--pic" role="img" focusable="false">
+      <use xlink:href="#c-icon-trek--pic"></use>
+    </svg>`;
+  }
+
   addFiles(event) {
     const files = Array.from(event.target.files);
 

data/app/components/trek/form/image_field_component.rb

@@ -7,6 +7,13 @@ module Trek
       include StimulusHelpers
       include Turbo::FramesHelper
 
+      # Ensure the placeholder icon is in the sprite even when an image exists,
+      # because the JS removeImage action needs it.
+      def before_render
+        Current.icons ||= []
+        Current.icons << "trek--pic" unless Current.icons.include?("trek--pic")
+      end
+
       private
 
       def preview
@@ -48,6 +55,12 @@ module Trek
         }.merge(stimulus_target_hash("fileInput"))
       end
 
+      def remove_button_data_attributes
+        {
+          action: stimulus_action("removeImage")
+        }
+      end
+
       def button_text
         image&.exists? ? t("admin.actions.replace") : t("admin.actions.browse")
       end

data/app/components/trek/form/switch_box_component.rb

@@ -53,6 +53,7 @@ module Trek
       end
 
       def label_text
+        content ||= options[:label]
         content ||= ActionView::Helpers::Tags::Translator.new(object, object_name, method_name, scope: "helpers.label").translate
         content ||= method_name.humanize
         content

data/app/components/trek/tabs_component/tabs_component.css

@@ -1,6 +1,7 @@
 /* Use component-local class names and add them to HTML via #class_for(name) helper */
 
 .root {
+  margin-bottom: 10rem;
   max-width: 64rem;
 }
 

data/app/controllers/concerns/trek/model.rb

@@ -34,8 +34,11 @@ module Trek
     # Returns model element as an array of symbols for route building.
     # For namespaced models like Missive::List, returns [:missive, :list].
     # For non-namespaced models like Page, returns [:page].
+    # Derived from collection (which preserves namespace) rather than element
+    # (which demodulizes).
     def model_element_route
-      model_name.element.split("/").map(&:to_sym)
+      parts = model_name.collection.split("/")
+      (parts[0...-1] + [parts.last.singularize]).map(&:to_sym)
     end
 
     def model_intro(action: nil)

data/config/locales/trek.en.yml

@@ -43,6 +43,7 @@ en:
         n: New %{resource}
       reorder_resource:
         n: Reorder %{resources}
+      remove: Remove
       replace: Replace
       search_resource:
         n: Search for a %{resource}
@@ -215,10 +216,12 @@ en:
         h4: 4th-level title
         hard_break: Line break
         horizontal_rule: Horizontal line
+        image: Image
         italic: Italic
         link: Link
         paragraph: Paragraph
         placeholder: Write something…
+        prompt: Action
         redo: Redo the last operation
         undo: Undo the last operation
     list:

data/config/locales/trek.fr.yml

@@ -49,6 +49,7 @@ fr:
         f: Réorganiser les %{resources}
         m: Réorganiser les %{resources}
         m_alt: Réorganiser les %{resources}
+      remove: Enlever
       replace: Remplacer
       search_resource:
         "n": Rechercher un·e %{resources}

data/docs/.vitepress/config.mjs

@@ -0,0 +1,133 @@
+import { defineConfig } from 'vitepress'
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  title: "Trek",
+  description: "A modern content management & back-office system for Ruby on Rails",
+  lang: 'en-US',
+  lastUpdated: true,
+  themeConfig: {
+    logo: { src: '/logo.svg', width: 24, height: 24 },
+
+    // https://vitepress.dev/reference/default-theme-config
+    nav: [
+      { text: 'Home', link: '/' },
+      { text: 'Guide', link: '/what-is-trek' },
+      { text: 'Reference', link: '/reference/' }
+    ],
+
+    sidebar: {
+      '/': [
+        {
+          text: 'Introduction',
+          items: [
+            { text: "What's Trek?", link: '/what-is-trek' },
+            { text: 'Getting started', link: '/getting-started' }
+          ]
+        },
+        {
+          text: 'Guides',
+          items: [
+            { text: 'How to customize Trek', link: '/customize' }
+          ]
+        },
+        {
+          text: 'Reference',
+          items: [
+            { text: 'Reference manual', link: '/reference/' }
+          ]
+        }
+      ],
+
+      '/reference/': [
+        { text: 'Overview', link: '/reference/' },
+        {
+          text: 'Generators',
+          collapsed: false,
+          items: [
+            { text: 'Installer', link: '/reference/generators/install' },
+            { text: 'Admin user', link: '/reference/generators/admin-user' },
+            { text: 'Scaffold', link: '/reference/generators/scaffold' },
+            { text: 'Taxonomies', link: '/reference/generators/taxonomies' }
+          ]
+        },
+        {
+          text: 'Models',
+          collapsed: false,
+          items: [
+            { text: 'Page', link: '/reference/models/page' },
+            { text: 'PageVersion', link: '/reference/models/page-version' },
+            { text: 'PagePath', link: '/reference/models/page-path' },
+            { text: 'Fragment', link: '/reference/models/fragment' },
+            { text: 'MenuNode', link: '/reference/models/menu-node' },
+            { text: 'ExternalLink', link: '/reference/models/external-link' },
+            { text: 'User', link: '/reference/models/user' },
+            { text: 'Tag & taxonomy', link: '/reference/models/tag' },
+            { text: 'Current', link: '/reference/models/current' }
+          ]
+        },
+        {
+          text: 'Concerns',
+          collapsed: false,
+          items: [
+            { text: 'Translatable', link: '/reference/concerns/translatable' },
+            { text: 'Contentable', link: '/reference/concerns/contentable' },
+            { text: 'Formattable', link: '/reference/concerns/formattable' },
+            { text: 'Fragmentable', link: '/reference/concerns/fragmentable' },
+            { text: 'Pageable', link: '/reference/concerns/pageable' },
+            { text: 'Sluggable', link: '/reference/concerns/sluggable' },
+            { text: 'Pathable', link: '/reference/concerns/pathable' },
+            { text: 'SearchEngineOptimizable', link: '/reference/concerns/search-engine-optimizable' },
+            { text: 'Versionable', link: '/reference/concerns/versionable' },
+            { text: 'Sectionable', link: '/reference/concerns/sectionable' },
+            { text: 'Orderable', link: '/reference/concerns/orderable' },
+            { text: 'Keyable', link: '/reference/concerns/keyable' },
+            { text: 'Searchable', link: '/reference/concerns/searchable' },
+            { text: 'Taggable', link: '/reference/concerns/taggable' },
+            { text: 'Phonable', link: '/reference/concerns/phonable' }
+          ]
+        },
+        {
+          text: 'Back-office',
+          collapsed: false,
+          items: [
+            { text: 'Controllers', link: '/reference/controllers' },
+            { text: 'Forms', link: '/reference/forms' },
+            { text: 'Formatters', link: '/reference/formatters' },
+            { text: 'Policies', link: '/reference/policies' },
+            { text: 'Uploaders', link: '/reference/uploaders' }
+          ]
+        },
+        {
+          text: 'Front-end',
+          collapsed: false,
+          items: [
+            { text: 'Components', link: '/reference/components' },
+            { text: 'Icons', link: '/reference/icons' }
+          ]
+        },
+        {
+          text: 'Configuration',
+          collapsed: false,
+          items: [
+            { text: 'Environment variables', link: '/reference/environment-variables' }
+          ]
+        }
+      ]
+    },
+
+    search: {
+      provider: 'local'
+    },
+
+    socialLinks: [
+      { icon: { svg: "<svg height='800' preserveAspectRatio='xMidYMid' viewBox='-18.5 0 293 293' width='800' xmlns='http://www.w3.org/2000/svg'><path d='m76.7478977 97.4337652-.1626607-.1626607-36.1106776 36.1106775 87.6741226 87.511462 36.110678-35.948017 51.563445-51.563445-36.110678-36.1106775v-.1626607h-103.12689z'/><path d='m127.823361.97596426-127.6886576 73.19731944v146.3946393l127.6886576 73.197319 127.688657-73.197319v-146.3946393zm103.28955 205.60313774-103.28955 59.533819-103.2895511-59.533819v-118.7423187l103.2895511-59.5338198 103.28955 59.5338198z'/></svg>" }, link: 'https://rubygems.org/gems/trek' },
+      { icon: 'npm', link: 'https://www.npmjs.com/package/trek' }
+    ],
+
+    footer: {
+      message: 'Released under the MIT License.',
+      copyright: 'Copyright © Etamin Studio'
+    }
+  }
+})

data/docs/.vitepress/theme/index.js

@@ -0,0 +1,17 @@
+// https://vitepress.dev/guide/custom-theme
+import { h } from 'vue'
+import DefaultTheme from 'vitepress/theme'
+import './style.css'
+
+/** @type {import('vitepress').Theme} */
+export default {
+  extends: DefaultTheme,
+  Layout: () => {
+    return h(DefaultTheme.Layout, null, {
+      // https://vitepress.dev/guide/extending-default-theme#layout-slots
+    })
+  },
+  enhanceApp({ app, router, siteData }) {
+    // ...
+  }
+}

data/docs/.vitepress/theme/style.css

@@ -0,0 +1,139 @@
+/**
+ * Customize default theme styling by overriding CSS variables:
+ * https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css
+ */
+
+/**
+ * Colors
+ *
+ * Each colors have exact same color scale system with 3 levels of solid
+ * colors with different brightness, and 1 soft color.
+ * 
+ * - `XXX-1`: The most solid color used mainly for colored text. It must
+ *   satisfy the contrast ratio against when used on top of `XXX-soft`.
+ *
+ * - `XXX-2`: The color used mainly for hover state of the button.
+ *
+ * - `XXX-3`: The color for solid background, such as bg color of the button.
+ *   It must satisfy the contrast ratio with pure white (#ffffff) text on
+ *   top of it.
+ *
+ * - `XXX-soft`: The color used for subtle background such as custom container
+ *   or badges. It must satisfy the contrast ratio when putting `XXX-1` colors
+ *   on top of it.
+ *
+ *   The soft color must be semi transparent alpha channel. This is crucial
+ *   because it allows adding multiple "soft" colors on top of each other
+ *   to create a accent, such as when having inline code block inside
+ *   custom containers.
+ *
+ * - `default`: The color used purely for subtle indication without any
+ *   special meanings attched to it such as bg color for menu hover state.
+ *
+ * - `brand`: Used for primary brand colors, such as link text, button with
+ *   brand theme, etc.
+ *
+ * - `tip`: Used to indicate useful information. The default theme uses the
+ *   brand color for this by default.
+ *
+ * - `warning`: Used to indicate warning to the users. Used in custom
+ *   container, badges, etc.
+ *
+ * - `danger`: Used to show error, or dangerous message to the users. Used
+ *   in custom container, badges, etc.
+ * -------------------------------------------------------------------------- */
+
+ :root {
+  --vp-c-default-1: var(--vp-c-gray-1);
+  --vp-c-default-2: var(--vp-c-gray-2);
+  --vp-c-default-3: var(--vp-c-gray-3);
+  --vp-c-default-soft: var(--vp-c-gray-soft);
+
+  --vp-c-brand-1: var(--vp-c-indigo-1);
+  --vp-c-brand-2: var(--vp-c-indigo-2);
+  --vp-c-brand-3: var(--vp-c-indigo-3);
+  --vp-c-brand-soft: var(--vp-c-indigo-soft);
+
+  --vp-c-tip-1: var(--vp-c-brand-1);
+  --vp-c-tip-2: var(--vp-c-brand-2);
+  --vp-c-tip-3: var(--vp-c-brand-3);
+  --vp-c-tip-soft: var(--vp-c-brand-soft);
+
+  --vp-c-warning-1: var(--vp-c-yellow-1);
+  --vp-c-warning-2: var(--vp-c-yellow-2);
+  --vp-c-warning-3: var(--vp-c-yellow-3);
+  --vp-c-warning-soft: var(--vp-c-yellow-soft);
+
+  --vp-c-danger-1: var(--vp-c-red-1);
+  --vp-c-danger-2: var(--vp-c-red-2);
+  --vp-c-danger-3: var(--vp-c-red-3);
+  --vp-c-danger-soft: var(--vp-c-red-soft);
+}
+
+/**
+ * Component: Button
+ * -------------------------------------------------------------------------- */
+
+:root {
+  --vp-button-brand-border: transparent;
+  --vp-button-brand-text: var(--vp-c-white);
+  --vp-button-brand-bg: var(--vp-c-brand-3);
+  --vp-button-brand-hover-border: transparent;
+  --vp-button-brand-hover-text: var(--vp-c-white);
+  --vp-button-brand-hover-bg: var(--vp-c-brand-2);
+  --vp-button-brand-active-border: transparent;
+  --vp-button-brand-active-text: var(--vp-c-white);
+  --vp-button-brand-active-bg: var(--vp-c-brand-1);
+}
+
+/**
+ * Component: Home
+ * -------------------------------------------------------------------------- */
+
+:root {
+  --vp-home-hero-name-color: transparent;
+  --vp-home-hero-name-background: -webkit-linear-gradient(
+    120deg,
+    #bd34fe 30%,
+    #41d1ff
+  );
+
+  --vp-home-hero-image-background-image: linear-gradient(
+    -45deg,
+    #bd34fe 50%,
+    #47caff 50%
+  );
+  --vp-home-hero-image-filter: blur(44px);
+}
+
+@media (min-width: 640px) {
+  :root {
+    --vp-home-hero-image-filter: blur(56px);
+  }
+}
+
+@media (min-width: 960px) {
+  :root {
+    --vp-home-hero-image-filter: blur(68px);
+  }
+}
+
+/**
+ * Component: Custom Block
+ * -------------------------------------------------------------------------- */
+
+:root {
+  --vp-custom-block-tip-border: transparent;
+  --vp-custom-block-tip-text: var(--vp-c-text-1);
+  --vp-custom-block-tip-bg: var(--vp-c-brand-soft);
+  --vp-custom-block-tip-code-bg: var(--vp-c-brand-soft);
+}
+
+/**
+ * Component: Algolia
+ * -------------------------------------------------------------------------- */
+
+.DocSearch {
+  --docsearch-primary-color: var(--vp-c-brand-1) !important;
+}
+

data/docs/customize.md

@@ -1,15 +1,71 @@
-## How to customize Trek
+# How to customize Trek
 
-### Admin panel branding
+Trek is designed to get you started fast with useful conventions, then get out of the way: most of the generated code lives in your application, so customizing it is just regular Rails work. Here are the most common entry points.
+
+## Admin panel branding
 
 You can pick the title and subtitle used in the admin panel header.
 
 ```yml
 # config/locales/en.yml
-admin:
-  brand:
-    title: My Awesome Project
-    subtitle: Back-office
+en:
+  admin:
+    brand:
+      title: My Awesome Project
+      subtitle: Back-office
+```
+
+## Favicon & logo
+
+Replace Trek's favicon with your own:
+
+- in SVG format at `app/assets/images/favicon.svg`
+- in PNG format (512 × 512 px) at `public/favicon.png`
+
+## Components
+
+Trek's UI components accept options where it matters:
+
+- **`Trek::Form::ActionsComponent`** — pick an `aspect` and add your own `classnames` to restyle form action bars.
+- **`Trek::DialogComponent`** — set the `title` and the buttons of modal dialogs.
+- **`Trek::Form::ContentEditorComponent`** — toggle the `nodes`, `blocks` and `floating` options to slim down the editor where full rich text isn't needed:
+
+```ruby
+f.content_editor :intro, nodes: false, floating: false
 ```
 
-Place your custom icon in `app/assets/favicon.svg` to use it in place of Trek's favicon.
+- **`Trek::LayoutComponent`** — use the `panel` slot to add your own side panel to admin screens.
+
+## Models
+
+The models generated by the installer and the scaffold are plain Active Record models in your `app/models`. Enable the commented-out hooks to opt into Trek features, for instance:
+
+```ruby
+class Book < ApplicationRecord
+  include Trek::Formattable
+  format_attributes Trek::TypographyFormatter, :title
+
+  include Trek::Translatable
+  translate_attributes :title
+
+  include RecordImageUploader::Attachment(:image)
+end
+```
+
+See the [concerns reference](/reference/) for the full list.
+
+## Policies
+
+Each scaffolded resource gets its own policy in `app/policies/admin`. Adjust the rules and `permitted_attributes` per role — the [policies reference](/reference/policies) shows the generated default.
+
+## Theming
+
+Trek's admin supports light, dark and auto themes, selectable per user. The design tokens are based on [Radix colors](https://www.radix-ui.com/colors); override the CSS custom properties in your own stylesheet to adapt the palette.
+
+## Dependencies configuration
+
+The installer configures Shrine, Postmark, Sorcery, ActionPolicy, Mobility and friends with sensible defaults — through initializers generated **in your app**. You can edit them at any time:
+
+- `config/initializers/shrine.rb` — storage backends, upload limits
+- `config/credentials.yml.enc` — Postmark API token (`EDITOR="code --wait" bin/rails credentials:edit`)
+- `config/i18n-tasks.yml` — locale management rules

data/docs/getting-started.md

@@ -0,0 +1,160 @@
+# Getting started
+
+This guide takes you from an empty directory to a working Rails application with a Trek back-office.
+
+## Prerequisites
+
+Make sure the following are installed:
+
+- Ruby 3.1+
+- Rails 7.0+
+- PostgreSQL 12+
+- Node 20+
+- Yarn 3.x
+- libvips
+
+Check your Rails version:
+
+```sh
+rails -v
+```
+
+If it's older than 7.0, run `gem install rails` to upgrade.
+
+Check your Yarn version:
+
+```sh
+yarn -v
+```
+
+If it's not a 3.x version, run:
+
+```sh
+corepack enable
+corepack install --global yarn@3
+```
+
+## Create your Rails project
+
+Replace `helloworld` with your own project name:
+
+```sh
+export TREK_PROJECT_NAME=helloworld
+rails new $TREK_PROJECT_NAME -j esbuild -d postgresql \
+  --skip-action-mailbox --skip-action-text --skip-action-cable \
+  --skip-active-storage --skip-jbuilder --skip-test --skip-system-test
+cd $TREK_PROJECT_NAME
+```
+
+## Get access to Trek
+
+Trek is distributed as a gem and an NPM package from Etamin Studio's GitLab. [Create a deploy token](https://git.etaminstud.io/etaminstudio/trek/-/settings/repository#js-deploy-tokens) associated to the Trek project:
+
+- **Name**: your project name (e.g. `helloworld`)
+- **Username**: your project name (e.g. `helloworld`)
+- **Scopes**: `read_repository`, `read_package_registry`
+
+Export the generated token (replace `XXXXXXXXXXX`):
+
+```sh
+export TREK_DEPLOY_TOKEN=XXXXXXXXXXX
+```
+
+## Install the gem
+
+Add the deploy token to your project's local Bundler config:
+
+```sh
+bundle config git.etaminstud.io $TREK_PROJECT_NAME:$TREK_DEPLOY_TOKEN
+```
+
+Install the gem and add it to your `Gemfile`:
+
+```sh
+bundle add trek --git https://git.etaminstud.io/etaminstudio/trek.git --branch main
+```
+
+Prepare the NPM package installation:
+
+```sh
+export NPM_AUTH_TOKEN=$TREK_DEPLOY_TOKEN
+```
+
+## Run the installer
+
+```sh
+rails g trek:install
+```
+
+The installer will:
+
+- install all dependencies ([see the full list](/what-is-trek#what-you-get))
+- 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
+- set up authentication (Sorcery), authorization (ActionPolicy), uploads (Shrine), emails (Postmark), i18n, linting, CI and more
+
+### Configure Postmark (optional)
+
+If you already know your [Postmark](https://postmarkapp.com) credentials, define this ENV variable **before** running the installer so it gets injected into the credentials file automatically:
+
+```sh
+export POSTMARK_API_TOKEN=YOUR_TOKEN
+```
+
+You can also do it manually afterwards:
+
+```sh
+EDITOR="code --wait" bin/rails credentials:edit
+```
+
+### Configure DeepL (optional)
+
+DeepL is used to translate locale files automatically when running the scaffold generator. To enable it, define this ENV variable before running the installer:
+
+```sh
+export DEEPL_AUTH_KEY=YOUR_TOKEN
+```
+
+Without it, translations won't happen automatically and you will have to edit each non-English locale file by hand.
+
+## Create an admin user
+
+Set `ADMIN_EMAIL` and `ADMIN_PASSWORD` in your `.env`, then run:
+
+```sh
+rails g trek:admin:user
+```
+
+## Start the server
+
+```sh
+bin/dev
+```
+
+Open `http://localhost:3000/admin` and sign in with your admin credentials. Welcome to your back-office! 🏔
+
+## Scaffold your first resource
+
+Trek's scaffold generator creates everything an admin panel needs for a model:
+
+```sh
+rails g trek:scaffold Book title:string intro:text
+```
+
+This generates, in a single command:
+
+- the `Book` model and migration (calling the Rails `model` generator behind the scenes)
+- the `Admin::BooksController` based on `Trek::ResourceController`
+- the index, show, new, edit views and form partial
+- the `Admin::BookPolicy` with role-based permissions
+- the admin routes
+- the locale files (auto-translated via DeepL if configured)
+- a menu entry in the admin dashboard
+
+Next steps:
+
+- [Customize Trek](/customize) — branding, favicon, components
+- [Reference manual](/reference/) — generators, models, components and more