b4um_generators 0.1.0

data/lib/generators/b4um/help/help_generator.rb

@@ -0,0 +1,755 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module B4um
+  module Generators
+    class HelpGenerator < Rails::Generators::Base
+      desc "Shows an overview of the available b4um generators and features"
+
+      def show_help
+        say <<~TEXT
+
+          b4um Generators
+          ===============
+
+          INSTALLATION
+
+            bin/rails generate b4um:install
+
+          Installs the b4um base setup:
+
+            - b4um component stylesheets
+            - Navigation
+            - Navigation Stimulus controller
+            - Image preview Stimulus controller
+            - Image lightbox Stimulus controller
+            - Helper methods
+            - Layout integration
+            - Bento / card components
+
+          During installation, optional features can be selected:
+
+            - bcrypt for password support
+            - Active Storage for image attachments
+            - Hero section
+            - Footer
+            - Footer sitemap
+            - Cookie consent
+
+          The sitemap can only be installed when the footer is installed.
+
+          If an optional Gem is selected and is not already installed,
+          b4um adds it to the Gemfile and runs bundle install.
+
+          If Active Storage is selected and is not already installed,
+          b4um installs Active Storage and runs the database migration.
+
+
+          HERO
+
+          The installer can add an optional hero section.
+
+          Select the hero when running:
+
+            bin/rails generate b4um:install
+
+          The hero partial is created at:
+
+            app/views/shared/_hero.html.erb
+
+          The generated hero works without an image by default.
+
+          The template contains examples for:
+
+            - Hero title and text
+            - Optional action link
+            - Optional hero image
+
+          Hero CSS classes use the b4um-hero prefix.
+
+
+          BENTO / CARDS
+
+          b4um includes a responsive Bento-style card system.
+
+          Basic example:
+
+            <div class="b4um-grid">
+              <article class="b4um-card">
+                ...
+              </article>
+            </div>
+
+          Available card variants:
+
+            b4um-card
+            b4um-card--wide
+            b4um-card--large
+            b4um-card--full
+            b4um-card--soft
+
+          Card content classes include:
+
+            b4um-card__eyebrow
+            b4um-card__title
+            b4um-card__text
+            b4um-card__actions
+            b4um-card__media
+            b4um-card__image
+
+          The Bento grid is responsive and automatically adapts
+          to tablet and mobile layouts.
+
+          b4um scaffolds automatically use the Bento card system
+          for generated index pages.
+
+          Cards use a repeating layout pattern:
+
+            1 - wide
+            2 - soft
+            3 - normal
+            4 - large
+            5 - normal
+
+          Long text fields are shortened on index cards while the
+          complete content remains visible on the show page.
+
+
+          FOOTER
+
+          The installer can add an optional footer.
+
+          Select the footer when running:
+
+            bin/rails generate b4um:install
+
+          The footer partial is created at:
+
+            app/views/shared/_footer.html.erb
+
+          The generated footer includes:
+
+            - Automatic current year
+            - Application name placeholder
+            - Automatic legal page links generated by b4um:controller
+            - Optional sitemap partial
+            - Optional cookie settings control
+
+          Footer CSS classes use the b4um-footer prefix.
+
+          The sitemap is not hard-coded into the footer. When the
+          sitemap is selected during installation, b4um creates a
+          separate sitemap partial and renders it inside the footer.
+
+
+          SITEMAP
+
+          The installer can optionally add a sitemap to the footer.
+
+          The footer must be installed before the sitemap can be selected.
+
+          During installation, b4um asks:
+
+            Add a sitemap to the footer? (y/n)
+
+          When the sitemap is enabled, the number of sitemap columns
+          can be selected:
+
+            Number of sitemap columns [4]:
+
+          The sitemap supports between 2 and 5 columns.
+
+          Press Enter to use the default of 4 columns.
+
+          After selecting the number of columns, b4um asks for the
+          title of each selected column.
+
+          With the default four-column setup:
+
+            Sitemap column 1 title [Kontakt]:
+            Sitemap column 2 title [Inhalte]:
+            Sitemap column 3 title [Service]:
+            Sitemap column 4 title [Mehr]:
+
+          When five columns are selected, an additional title is
+          requested:
+
+            Sitemap column 5 title [Weitere]:
+
+          Press Enter to keep the default title shown in brackets.
+
+          Only the selected number of sitemap columns is written to
+          the configuration.
+
+          The sitemap partial is created at:
+
+            app/views/shared/_sitemap.html.erb
+
+          The sitemap Stimulus controller is created at:
+
+            app/javascript/controllers/sitemap_controller.js
+
+          The sitemap partial is rendered inside:
+
+            app/views/shared/_footer.html.erb
+
+          The sitemap configuration is stored in:
+
+            config/b4um.yml
+
+          Example using the default four columns:
+
+            sitemap:
+              - key: column_1
+                title: Kontakt
+              - key: column_2
+                title: Inhalte
+              - key: column_3
+                title: Service
+              - key: column_4
+                title: Mehr
+
+            legal_links:
+              placement: footer
+
+          A two-column sitemap contains only column_1 and column_2.
+
+          A five-column sitemap additionally contains:
+
+            column_5
+
+          The sitemap column titles can also be changed later by
+          editing config/b4um.yml.
+
+          Available column keys range from:
+
+            column_1
+
+          through:
+
+            column_5
+
+          Only keys for columns that exist in the current sitemap
+          configuration should be used.
+
+          The keys identify the sitemap columns independently of their
+          visible titles.
+
+          On larger screens, the available sitemap columns are
+          distributed automatically across the footer.
+
+          On smaller screens, the sitemap uses its responsive
+          collapsible layout.
+
+          Controller actions can be added directly to a sitemap column
+          with --sitemap:
+
+            bin/rails generate b4um:controller Pages faq support --sitemap=column_3
+
+          When --sitemap is used, the generated actions are added to the
+          selected sitemap column instead of the main navigation.
+
+          Generated sitemap links use Rails route helpers.
+
+          Example:
+
+            links:
+              - title: FAQ
+                route: faq_path
+
+          Only valid Rails path helpers ending in _path are resolved
+          by the b4um sitemap helper.
+
+          Legal pages can remain in the separate legal footer area:
+
+            legal_links:
+              placement: footer
+
+          This is the default configuration.
+
+          Legal pages can alternatively be placed in any existing
+          sitemap column:
+
+            legal_links:
+              placement: column_4
+
+          When legal pages are assigned to a sitemap column, b4um adds
+          them to that column automatically and does not duplicate them
+          in the separate legal footer area.
+
+          The placement uses the sitemap column key, not its visible
+          title. This allows sitemap column titles to be changed freely.
+
+
+          COOKIE CONSENT
+
+          The installer can optionally add cookie consent.
+
+          During installation, b4um asks:
+
+            Add cookie consent? (y/n)
+
+          Cookie consent can be installed independently of the footer.
+
+          The cookie consent partial is created at:
+
+            app/views/shared/_cookie_consent.html.erb
+
+          The cookie consent Stimulus controller is created at:
+
+            app/javascript/controllers/cookie_consent_controller.js
+
+          The visitor's consent choice is stored in the browser's
+          local storage.
+
+          If both the footer and cookie consent are installed, b4um
+          automatically adds a Cookie-Einstellungen control to the
+          footer.
+
+          This control allows visitors to reopen the cookie consent
+          banner and change their choice later.
+
+          Cookie consent can also be installed without a footer. In
+          that case, the cookie consent banner still works, but no
+          cookie settings control is added to the footer.
+
+
+          SCAFFOLD
+
+            bin/rails generate b4um:scaffold MODEL ATTRIBUTES
+
+          Example:
+
+            bin/rails generate b4um:scaffold User name:string email:string
+
+          b4um scaffold features:
+
+            - b4um forms
+            - b4um index, show, new and edit views
+            - Bento index layout by default
+            - Optional table index layout
+            - Automatic navigation entry
+            - Active navigation state
+            - Form validation errors
+            - Flash messages
+            - Password field support
+            - Optional readable URL parameters
+
+          The default index uses the b4um Bento card layout.
+
+          To generate a table index instead, use:
+
+            --layout=table
+
+          Example:
+
+            bin/rails generate b4um:scaffold Product name:string description:text price:decimal status:string --layout=table
+
+          Table layouts automatically:
+
+            - Use the responsive b4um table component
+            - Shorten text fields to 100 characters
+            - Display a status field as a b4um badge
+            - Include an actions column
+            - Include the b4um empty state
+
+
+          READABLE URL PARAMETERS
+
+          b4um scaffolds can generate readable URLs while keeping
+          the database ID in the URL.
+
+          Use:
+
+            --param=ATTRIBUTE
+
+          Example:
+
+            bin/rails generate b4um:scaffold Article title:string body:text --param=title
+
+          This generates:
+
+            def to_param
+              "\#{id} \#{title}".parameterize
+            end
+
+          Example URL:
+
+            /articles/17-my-first-article
+
+          The ID remains part of the URL, so the standard Rails
+          resource lookup can still be used.
+
+          The readable part of the URL is updated automatically
+          when the selected attribute changes.
+
+
+          PASSWORDS
+
+          For password authentication, use:
+
+            password_digest:string
+
+          Example:
+
+            bin/rails generate b4um:scaffold User name:string email:string password_digest:string
+
+          The b4um scaffold automatically creates password fields
+          instead of displaying password_digest directly.
+
+          Password support requires bcrypt.
+
+          Select bcrypt when running:
+
+            bin/rails generate b4um:install
+
+          b4um adds bcrypt to the Gemfile if necessary and installs
+          the selected Gem automatically.
+
+
+          ACTIVE STORAGE / IMAGES
+
+          Image attachments require Active Storage.
+
+          Select Active Storage when running:
+
+            bin/rails generate b4um:install
+
+          b4um installs Active Storage and runs the required database
+          migration automatically if Active Storage is not already installed.
+
+
+          Single image:
+
+            image:attachment
+
+          Example:
+
+            bin/rails generate b4um:scaffold Article title:string image:attachment
+
+          Multiple images:
+
+            images:attachments
+
+          Example:
+
+            bin/rails generate b4um:scaffold Gallery title:string images:attachments
+
+          Image features:
+
+            - Active Storage integration
+            - Image preview before saving
+            - Existing image preview while editing
+            - Add new images without removing existing images
+            - Remove individual existing images
+            - Image lightbox
+            - Previous / next navigation
+            - Mouse and touch swipe
+            - Keyboard navigation
+
+
+          BENTO
+
+            bin/rails generate b4um:bento MODEL
+
+          Generates a reusable b4um Bento partial for an existing model.
+
+          Example:
+
+            bin/rails generate b4um:bento Product
+
+          The default layout is Grid.
+
+          Available layouts:
+
+            bin/rails generate b4um:bento Product
+            bin/rails generate b4um:bento Product --layout=grid
+            bin/rails generate b4um:bento Product --layout=list
+            bin/rails generate b4um:bento Product --layout=alternating
+            bin/rails generate b4um:bento Product --layout=bento
+
+          Layouts:
+
+            grid
+              The default three-column card grid.
+              Adapts to two columns on tablets and one column on mobile.
+
+            list
+              A compact horizontal list layout.
+              Actions move below the content on mobile.
+
+            alternating
+              A spacious alternating layout with the action area
+              switching between the left and right side.
+              Uses a single-column layout on mobile.
+
+            bento
+              The classic Bento layout with mixed card sizes.
+
+          Use --layout=bento to explicitly generate the classic
+          Bento design.
+
+          The model and its resource partial must already exist.
+
+          Example resource partial:
+
+            app/views/products/_product.html.erb
+
+          b4um scaffold resource partials support compact mode.
+          In Bento cards, text fields are shortened to 160 characters.
+
+          The generated partial is created at:
+
+            app/views/products/_bento.html.erb
+
+          Bento features:
+
+            - Responsive b4um Bento grid
+            - Repeating card layout with different card sizes
+            - Uses the existing resource partial for card content
+            - Actions area with a Show button
+            - No migrations, routes or controllers are generated
+
+          Render the partial from an index view with:
+
+            <%= render "bento", products: @products %>
+
+          The partial uses a local collection, so it can also be
+          reused with another collection:
+
+            <%= render "products/bento", products: @featured_products %>
+
+
+          TABLE
+
+            bin/rails generate b4um:table MODEL FIELDS
+
+          Generates a reusable b4um table partial for an existing model.
+
+          Example:
+
+            bin/rails generate b4um:table Product name:string description:text price:decimal status:string
+
+          The model must already exist.
+
+          The generated partial is created at:
+
+            app/views/products/_table.html.erb
+
+          Table features:
+
+            - Responsive b4um table component
+            - Typed field definitions
+            - Text fields shortened to 100 characters
+            - Status field displayed as a b4um badge
+            - Actions column with a Show button
+            - No migrations, routes or controllers are generated
+
+          Render the partial from an index view with:
+
+            <%= render "table", products: @products %>
+
+          The partial uses a local collection, so it can also be
+          reused with another collection:
+
+            <%= render "products/table", products: @featured_products %>
+
+
+          CONTROLLER
+
+            bin/rails generate b4um:controller NAME ACTIONS
+
+          Example:
+
+            bin/rails generate b4um:controller Pages home about impressum agb
+
+          b4um controller features:
+
+            - Uses the standard Rails controller generator
+            - Creates the requested actions and views
+            - Adds regular action links to the b4um navigation automatically
+            - Adds legal pages to the b4um footer automatically
+            - German legal pages: impressum, datenschutz, agb
+            - English legal pages: imprint, privacy, privacy_policy,
+              terms, terms_and_conditions
+            - Legal pages are not added to the main navigation
+            - Footer links require the b4um footer to be installed
+
+          Controller actions can also be assigned directly to a sitemap
+          column with --sitemap.
+
+          Example:
+
+            bin/rails generate b4um:controller Pages faq support --sitemap=column_3
+
+
+          PAGINATION
+
+            bin/rails generate b4um:pagination MODEL
+
+          Adds server-side b4um pagination to an existing resource.
+
+          Example:
+
+            bin/rails generate b4um:pagination Product
+
+          By default, 20 records are displayed per page.
+
+          Use a custom page size with:
+
+            bin/rails generate b4um:pagination Product --per-page=50
+
+          The model, controller and index view must already exist.
+
+          Pagination features:
+
+            - Server-side pagination using Active Record limit and offset
+            - No additional pagination gem required
+            - Previous and Next navigation
+            - Numbered page navigation
+            - Preserves existing query parameters
+            - Works with b4um Bento and Table layouts
+            - Invalid or excessive page numbers are handled safely
+            - Shared pagination core can be reused by other b4um features
+
+
+          INFINITE SCROLL
+
+            bin/rails generate b4um:infinite_scroll MODEL
+
+          Adds automatic infinite scrolling to an existing resource.
+
+          Example:
+
+            bin/rails generate b4um:infinite_scroll Product
+
+          By default, 20 records are loaded per page.
+
+          Use a custom page size with:
+
+            bin/rails generate b4um:infinite_scroll Product --per-page=50
+
+          The model, controller and index view must already exist.
+
+          Infinite Scroll features:
+
+            - Loads additional records automatically while scrolling
+            - Server-side pagination using Active Record limit and offset
+            - No additional pagination gem required
+            - Works with b4um Bento and Table layouts
+            - Preserves existing query parameters
+            - Stops automatically after the final page
+            - Replaces existing b4um pagination navigation
+            - Safe repeated generator runs
+
+
+          SEARCH
+
+            bin/rails generate b4um:search MODEL
+
+          Adds database-backed search to an existing resource.
+
+          Example:
+
+            bin/rails generate b4um:search Product
+
+          The model, controller and index view must already exist.
+
+          Search features:
+
+            - Searches all string and text columns
+            - Case-insensitive partial matching
+            - Safely escapes search terms
+            - Blank searches return the complete collection
+            - Works with b4um Bento and Table layouts
+            - Works with b4um Pagination and Infinite Scroll
+            - Preserves the search query while navigating pages
+            - No additional search gem required
+            - Safe repeated generator runs
+
+
+          COMMENTS
+
+            bin/rails generate b4um:comments MODEL
+
+          Example:
+
+            bin/rails generate b4um:comments Article
+
+          Adds polymorphic comments to an existing model.
+
+          b4um comments features:
+
+            - Polymorphic Comment model
+            - Comment association on the selected model
+            - Nested create and destroy routes
+            - Comments controller
+            - Comment list and form
+            - Delete confirmation
+            - b4um form and card styling
+            - Support for multiple commentable models
+            - Safe repeated generator runs
+
+          Additional models can use the same comments system:
+
+            bin/rails generate b4um:comments Product
+
+          Existing b4um comments controllers are extended automatically.
+          Unknown custom comments controllers are left unchanged and cause
+          the generator to stop with an error.
+
+
+          TRIX / RICH TEXT
+
+            bin/rails generate b4um:trix MODEL ATTRIBUTE
+
+          Adds Action Text with Trix to an existing b4um resource.
+
+          Example:
+
+            bin/rails generate b4um:trix Article content
+
+          The model and form must already exist.
+
+          The generator adds:
+
+            has_rich_text :content
+
+          and replaces the selected form field with a rich text editor:
+
+            form.rich_text_area :content
+
+          Trix / Rich Text features:
+
+            - Installs Action Text automatically when necessary
+            - Adds the rich text association to the model
+            - Replaces only the selected form field
+            - Preserves compact Bento text using plain text
+            - Image lightbox for images inside rich text
+            - Previous / next image navigation
+            - Mouse and touch swipe
+            - Keyboard navigation
+            - Responsive image galleries
+            - Sticky Trix toolbar
+            - Headings H1 through H6
+            - Left, center, and right text alignment
+            - Text and background colors
+            - Horizontal rules
+            - Editable DIV, SECTION, and ARTICLE containers with IDs
+            - Container formatting remains fully editable
+            - Active container buttons can remove the wrapper again
+            - Safe repeated generator runs
+
+
+          HELP
+
+            bin/rails generate b4um:help
+
+          Shows this overview.
+
+        TEXT
+      end
+    end
+  end
+end