glib-web 4.39.1 → 4.40.0

data/app/helpers/glib/json_ui/view_builder/panels.rb

@@ -2,16 +2,57 @@ require 'js_regex'
 
 class Glib::JsonUi::ViewBuilder
   module Panels
+    # Form panel for collecting user input and submitting data.
+    #
+    # A form panel automatically handles CSRF tokens, form validation, and data submission.
+    # It supports nested associations and dynamic field groups.
+    #
+    # @example Basic form with text field
+    #   panel.panels_form url: users_path, method: :post do |form|
+    #     form.fields_text prop: :name, label: 'Full Name'
+    #     form.fields_email prop: :email
+    #     form.fields_submit text: 'Create User'
+    #   end
+    #
+    # @example Form with model binding
+    #   panel.panels_form model: @user, autoValidate: true do |form|
+    #     form.fields_text prop: :name  # Automatically gets label from I18n
+    #     form.fields_email prop: :email
+    #     form.fields_submit text: 'Save'
+    #   end
+    #
+    # @example Form with onChange callback
+    #   panel.panels_form url: products_path, onChange: ->(action) do
+    #     action.http_get url: preview_product_path, silent: true
+    #   end do |form|
+    #     form.fields_select prop: :category_id, options: @categories
+    #   end
+    #
+    # @see https://guides.rubyonrails.org/form_helpers.html Rails Form Helpers
     class Form < View
       attr_reader :model_name # See Panels::Form.field_name
       attr_reader :_autoValidate
       attr_reader :disable_dirty_check
       attr_accessor :current_dynamic_group
 
+      # Action called when form is submitted successfully.
+      # Receives form data and can trigger navigation, dialogs, etc.
       action :onSubmit
+
+      # Action called whenever any form field value changes.
+      # Useful for real-time previews or dependent field updates.
       action :onChange
+
+      # Similar to onChange but triggers a page reload with new data.
+      # Use this when field changes require server-side processing.
       action :onChangeAndLoad
+
+      # Custom parameter name for form data when submitting.
+      # By default, uses the model name as the parameter namespace.
       string :paramNameForFormData
+
+      # If true, form submission will not use AJAX (full page reload).
+      # Set to true for file downloads or when you need full page refresh.
       bool :local
 
       def autoValidate(autoValidate)
@@ -265,28 +306,87 @@ class Glib::JsonUi::ViewBuilder
       end
     end
 
+    # List panel for displaying scrollable collections of items.
+    #
+    # Lists can display data in various formats (cards, rows, etc.) with support for
+    # pagination, infinite scrolling, and drag-and-drop reordering.
+    #
+    # @example Basic list with items
+    #   panel.panels_list width: 'matchParent', firstSection: ->(section) do
+    #     section.header childViews: ->(header) do
+    #       header.h2 text: 'Products'
+    #     end
+    #     @products.each do |product|
+    #       section.row childViews: ->(row) do
+    #         row.label text: product.name
+    #         row.label text: product.price
+    #       end
+    #     end
+    #   end
+    #
+    # @example List with pagination
+    #   panel.panels_list \
+    #     nextPage: { url: products_path(page: @page + 1) },
+    #     prevPage: { url: products_path(page: @page - 1) },
+    #     firstSection: ->(section) do
+    #       # ... items
+    #     end
+    #
+    # @example Responsive grid list
+    #   panel.panels_list responsiveCols: 3, firstSection: ->(section) do
+    #     @images.each do |image|
+    #       section.row childViews: ->(row) do
+    #         row.image url: image.url
+    #       end
+    #     end
+    #   end
     class List < View
-      # Setting this will turn the list into edit mode.
+      # Prefix for field names when list is used in edit mode.
+      # Setting this turns the list into an editable collection.
       string :fieldPrefix
 
-      # Setting this will enable title editing.
+      # Field name for editable title in list items.
+      # Enables inline editing of item titles.
       string :fieldTitleName
+
+      # Field name for editable subtitle in list items.
       string :fieldSubtitleName
+
+      # Field name for editable sub-subtitle in list items.
       string :fieldSubsubtitleName
 
-      # This can be used to implement "check all" and "uncheck all".
-      # deprecated?
+      # Conditional check values for "check all" / "uncheck all" functionality.
+      # @deprecated Use custom checkbox handling instead
       hash :fieldCheckValueIf
 
+      # Phoenix WebSocket configuration for real-time updates.
       hash :phoenixSocket
       # hash :actionCable
 
+      # Configuration for next page in pagination.
+      # Provide a hash with :url key pointing to the next page.
+      # @example { url: products_path(page: @page + 1) }
       hash :nextPage
+
+      # Configuration for previous page in pagination.
+      # Provide a hash with :url key pointing to the previous page.
       hash :prevPage
+
+      # Action triggered when user scrolls to the top of the list.
+      # Useful for pull-to-refresh functionality.
       action :onScrollToTop
+
+      # Action triggered when user scrolls to the bottom of the list.
+      # Useful for infinite scrolling / load more functionality.
       action :onScrollToBottom
 
+      # Number of columns for responsive grid layout.
+      # Items will be arranged in a grid with this many columns.
+      # @example responsiveCols: 3
       int :responsiveCols
+
+      # Configuration for drag-and-drop reordering support.
+      # @example dragSupport: { onDrop: { action: 'http/post', url: reorder_path } }
       hash :dragSupport
 
       def firstSection(block)
@@ -310,7 +410,11 @@ class Glib::JsonUi::ViewBuilder
       singleton_array :styleClass, :styleClasses
       array :events
       views :childViews
-      string :truncateLine
+      # Controls which end(s) of the timeline line to truncate.
+      # @see https://vuetifyjs.com/en/api/v-timeline/#props-truncate-line Vuetify Timeline truncateLine
+      enum :truncateLine, options: [:start, :end, :both]
+      enum :side, options: [:start, :end]
+      enum :direction, options: [:horizontal, :vertical]
     end
 
     # deprecated
@@ -445,82 +549,421 @@ class Glib::JsonUi::ViewBuilder
       end
     end
 
+    # Scrollable container panel for content that exceeds viewport height.
+    #
+    # Scroll panels automatically add scrollbars when content overflows.
+    # This is the most common container for page content.
+    #
+    # @example Basic scrollable content
+    #   page.scroll padding: glib_json_padding_body, childViews: ->(scroll) do
+    #     scroll.h1 text: 'Welcome'
+    #     scroll.p text: 'Long content here...'
+    #   end
     class Scroll < View
+      # Child components to display inside the scroll container.
+      # Provide a block that receives the view builder for adding content.
       views :childViews
     end
 
+    # Split panel for creating multi-column layouts with fixed side panels.
+    #
+    # Split panels divide the horizontal space into left, center, and right sections.
+    # The center section expands to fill available space, while side sections
+    # maintain their content width.
+    #
+    # @example Two-column layout
+    #   panel.panels_split width: 'matchParent', content: ->(content) do
+    #     content.left childViews: ->(left) do
+    #       left.button text: 'Menu'
+    #     end
+    #     content.center childViews: ->(center) do
+    #       center.h1 text: 'Main Content', width: 'matchParent'
+    #     end
+    #   end
+    #
+    # @example Three-column layout with alignment
+    #   panel.panels_split width: 'matchParent', align: 'middle', content: ->(content) do
+    #     content.left childViews: ->(left) do
+    #       left.button text: 'Back'
+    #     end
+    #     content.center childViews: ->(center) do
+    #       center.label text: 'Page Title'
+    #     end
+    #     content.right childViews: ->(right) do
+    #       right.button text: 'Save'
+    #     end
+    #   end
+    #
+    # @see app/views/json_ui/garage/panels/split.json.jbuilder Garage examples
     class Split < View
       # def content(block)
       #   block.call page.split_content_builder
       # end
-      string :align
+
+      # Vertical alignment of content within the split panel.
+      # Aligns items to top, middle, or bottom of the panel height.
+      # @example align: 'middle'
+      enum :align, options: [:top, :middle, :bottom]
+
+      # Content builder for defining left, center, and right sections.
+      # Use content.left, content.center, or content.right to define each section.
       panels_builder :content, :left, :center, :right
     end
 
+    # Responsive grid panel using Vuetify's 12-column grid system.
+    #
+    # Responsive panels automatically adjust layout based on screen size.
+    # Use panels_column children to define grid columns with breakpoint-specific sizing.
+    #
+    # @example Responsive two-column layout
+    #   panel.panels_responsive width: 'matchParent', childViews: ->(responsive) do
+    #     responsive.panels_column lg: { cols: 8 }, xs: { cols: 12 }, childViews: ->(col) do
+    #       col.h1 text: 'Main Content'
+    #     end
+    #     responsive.panels_column lg: { cols: 4 }, xs: { cols: 12 }, childViews: ->(col) do
+    #       col.h2 text: 'Sidebar'
+    #     end
+    #   end
+    #
+    # @example With hover effect
+    #   panel.panels_responsive \
+    #     styleClasses: ['card'],
+    #     hoverViews: ->(hover) { hover.label text: 'Click me!' },
+    #     onClick: ->(action) { action.windows_open url: product_path(@product) },
+    #     childViews: ->(panel) do
+    #       panel.h3 text: @product.name
+    #     end
+    #
+    # @see https://vuetifyjs.com/en/components/grids/ Vuetify Grid Documentation
+    # @see app/views/json_ui/garage/panels/responsive.json.jbuilder Garage examples
     class Responsive < View
+      # Child components to display in the responsive grid.
+      # Typically contains panels_column components.
       views :childViews
-      string :align
+
+      # Horizontal alignment of child columns.
+      # @example align: 'center'
+      enum :align, options: [:left, :center, :right]
+
+      # Action triggered when the panel is clicked.
+      # Makes the entire responsive panel clickable.
       action :onClick
+
+      # Views to display when hovering over the panel.
+      # Useful for showing tooltips or preview content on mouse hover.
       views :hoverViews
 
-      # Experimental
+      # Experimental: Additional panel sections for complex layouts.
+      # @note These are experimental features
       panels_builder :accessory, :header, :footer
     end
 
+    # Grid column for use within panels_responsive containers.
+    #
+    # Columns use Vuetify's 12-column grid system where you specify how many columns
+    # (out of 12) this component should occupy at different breakpoints.
+    #
+    # Breakpoints (from smallest to largest):
+    # - xs: < 600px (mobile phones)
+    # - sm: 600px - 960px (tablets)
+    # - md: 960px - 1264px (small laptops)
+    # - lg: 1264px - 1904px (desktops)
+    # - xl: 1904px - 2560px (large desktops)
+    # - xxl: > 2560px (ultra-wide displays)
+    #
+    # @example Responsive column that changes width at different screen sizes
+    #   responsive.panels_column \
+    #     lg: { cols: 4 },  # 4/12 = 1/3 width on large screens
+    #     md: { cols: 6 },  # 6/12 = 1/2 width on medium screens
+    #     xs: { cols: 12 }, # 12/12 = full width on mobile
+    #     childViews: ->(col) do
+    #       col.h3 text: 'Card Title'
+    #     end
+    #
+    # @example Column with responsive padding and ordering
+    #   responsive.panels_column \
+    #     lg: { cols: 8, order: 0, padding: { bottom: 0 } },
+    #     xs: { cols: 12, order: 1, padding: { bottom: 20 } },
+    #     childViews: ->(col) do
+    #       col.label text: 'Content'
+    #     end
+    #
+    # @see https://vuetifyjs.com/en/components/grids/ Vuetify Grid System
     class Column < View
+      # Configuration for xxl breakpoint (> 2560px).
+      # @example xxl: { cols: 3, order: 0, padding: { all: 16 } }
       hash :xxl
+
+      # Configuration for xl breakpoint (1904px - 2560px).
+      # @example xl: { cols: 4, hide: false }
       hash :xl
+
+      # Configuration for lg breakpoint (1264px - 1904px).
+      # @example lg: { cols: 6, order: 1 }
       hash :lg
+
+      # Configuration for md breakpoint (960px - 1264px).
+      # @example md: { cols: 8 }
       hash :md
+
+      # Configuration for sm breakpoint (600px - 960px).
+      # @example sm: { cols: 12 }
       hash :sm
+
+      # Configuration for xs breakpoint (< 600px).
+      # @example xs: { cols: 12, hide: false }
       hash :xs
 
+      # Configuration that applies only at xxl breakpoint.
       hash :xxlOnly
+
+      # Configuration that applies only at xl breakpoint.
       hash :xlOnly
+
+      # Configuration that applies only at lg breakpoint.
       hash :lgOnly
+
+      # Configuration that applies only at md breakpoint.
       hash :mdOnly
+
+      # Configuration that applies only at sm breakpoint.
       hash :smOnly
+
+      # Configuration that applies only at xs breakpoint.
       hash :xsOnly
 
+      # Configuration for xxl and smaller breakpoints.
       hash :xxlAndDown
+
+      # Configuration for xl and smaller breakpoints.
       hash :xlAndDown
+
+      # Configuration for lg and smaller breakpoints.
       hash :lgAndDown
+
+      # Configuration for md and smaller breakpoints.
+      # @example mdAndDown: { hide: true } # Hide on medium screens and below
       hash :mdAndDown
+
+      # Configuration for sm and smaller breakpoints.
       hash :smAndDown
+
+      # Configuration for xs breakpoint and below.
       hash :xsAndDown
 
+      # Child components to display inside the column.
       views :childViews
+
+      # Action triggered when the column is clicked.
       action :onClick
     end
 
+    # Vertical layout panel that stacks children vertically (top to bottom).
+    #
+    # Vertical panels use CSS flexbox with flex-direction: column.
+    # Children are arranged vertically and can be aligned or distributed in various ways.
+    #
+    # @example Basic vertical stacking
+    #   panel.panels_vertical backgroundColor: '#f0f0f0', childViews: ->(vert) do
+    #     vert.button text: 'Button 1'
+    #     vert.button text: 'Button 2'
+    #     vert.button text: 'Button 3'
+    #   end
+    #
+    # @example Centered content with equal spacing
+    #   panel.panels_vertical \
+    #     width: 'matchParent',
+    #     height: 300,
+    #     distribution: 'spaceEqually',
+    #     align: 'center',
+    #     childViews: ->(vert) do
+    #       vert.button text: 'Top'
+    #       vert.button text: 'Middle'
+    #       vert.button text: 'Bottom'
+    #     end
+    #
+    # @example Clickable vertical panel
+    #   panel.panels_vertical \
+    #     styleClasses: ['card'],
+    #     onClick: ->(action) { action.windows_open url: item_path(@item) },
+    #     childViews: ->(vert) do
+    #       vert.h3 text: @item.title
+    #       vert.p text: @item.description
+    #     end
+    #
+    # @see app/views/json_ui/garage/panels/vertical.json.jbuilder Garage examples
     class Vertical < View
+      # Child components to stack vertically.
       views :childViews
-      string :distribution
-      string :align
+
+      # How children should be distributed vertically.
+      # - 'fillEqually': Each child gets equal height
+      # - 'spaceEqually': Equal spacing between children
+      # @example distribution: 'fillEqually'
+      enum :distribution, options: [:fillEqually, :spaceEqually]
+
+      # Horizontal alignment of children.
+      # - 'left': Align to left edge
+      # - 'center': Center horizontally
+      # - 'right': Align to right edge
+      # @example align: 'center'
+      enum :align, options: [:left, :center, :right]
+
+      # Action triggered when the panel is clicked.
       action :onClick
     end
 
+    # Horizontal layout panel that arranges children side-by-side (left to right).
+    #
+    # Horizontal panels use CSS flexbox with flex-direction: row.
+    # Supports drag-and-drop reordering and various distribution modes.
+    #
+    # @example Basic horizontal layout
+    #   panel.panels_horizontal backgroundColor: '#f0f0f0', childViews: ->(horiz) do
+    #     horiz.button text: '1'
+    #     horiz.button text: '2'
+    #     horiz.button text: '3'
+    #   end
+    #
+    # @example With equal spacing and alignment
+    #   panel.panels_horizontal \
+    #     width: 300,
+    #     distribution: 'spaceEqually',
+    #     align: 'middle',
+    #     childViews: ->(horiz) do
+    #       horiz.button text: 'Left'
+    #       horiz.button text: 'Center'
+    #       horiz.button text: 'Right'
+    #     end
+    #
+    # @example With drag-and-drop reordering
+    #   panel.panels_horizontal \
+    #     width: 300,
+    #     dragSupport: {
+    #       onDrop: { action: 'http/post', url: reorder_items_path },
+    #       paramNameForFormData: 'order_data'
+    #     },
+    #     childViews: ->(horiz) do
+    #       @items.each do |item|
+    #         horiz.button id: "item_#{item.id}", text: item.name
+    #       end
+    #     end
+    #
+    # @example With overlapping items (negative margins)
+    #   panel.panels_horizontal \
+    #     distribution: 'overlap-3',  # 12px negative margin
+    #     childViews: ->(horiz) do
+    #       horiz.avatar url: user1.avatar_url
+    #       horiz.avatar url: user2.avatar_url
+    #       horiz.avatar url: user3.avatar_url
+    #     end
+    #
+    # @see app/views/json_ui/garage/panels/horizontal.json.jbuilder Garage examples
+    # @see https://vuetifyjs.com/en/styles/spacing/ Material Design Spacing
     class Horizontal < View
+      # Child components to arrange horizontally.
       views :childViews
+
+      # How children should be distributed horizontally.
+      # - 'fillEqually': Each child gets equal width
+      # - 'spaceEqually': Equal spacing between children
+      # - 'overlap-N': Negative spacing (N from 1-8, e.g., 'overlap-3' = -12px margin)
+      # - 'space-N': Positive spacing (N from 1-8, e.g., 'space-2' = 8px margin)
+      # @example distribution: 'spaceEqually'
+      # @note Uses Material Design spacing scale (4px increments)
       string :distribution
-      string :align
+
+      # Vertical alignment of children.
+      # - 'top': Align to top edge
+      # - 'middle': Center vertically
+      # - 'bottom': Align to bottom edge
+      # @example align: 'middle'
+      enum :align, options: [:top, :middle, :bottom]
+
+      # Action triggered when the panel is clicked.
       action :onClick
+
+      # Configuration for drag-and-drop reordering support.
+      # Enables users to reorder children by dragging them.
+      # @example dragSupport: { onDrop: { action: 'http/post', url: reorder_path }, paramNameForFormData: 'order' }
       hash :dragSupport, optional: [:onDrop, :paramNameForFormData, :paramNameForNewIndex]
     end
 
+    # Flow layout panel that wraps children like text (left to right, then top to bottom).
+    #
+    # Flow panels use CSS flexbox with flex-wrap, creating a responsive grid-like layout
+    # where children wrap to the next line when they exceed container width.
+    # Supports responsive gap and padding for different screen sizes.
+    #
+    # @example Basic flow layout
+    #   panel.panels_flow width: 300, innerPadding: { all: 10 }, childViews: ->(flow) do
+    #     (1..10).each do |n|
+    #       flow.button text: "Item #{n}"
+    #     end
+    #   end
+    #
+    # @example Responsive gaps and padding
+    #   panel.panels_flow \
+    #     width: 'matchParent',
+    #     xs: { gap: { x: 4, y: 4 }, padding: { all: 8 } },
+    #     md: { gap: { x: 16, y: 16 }, padding: { all: 24 } },
+    #     lg: { gap: { all: 32 } },
+    #     childViews: ->(flow) do
+    #       @products.each do |product|
+    #         flow.panels_vertical styleClasses: ['card'], childViews: ->(card) do
+    #           card.image url: product.image_url
+    #           card.h4 text: product.name
+    #         end
+    #       end
+    #     end
+    #
+    # @example Tag cloud with inner padding
+    #   panel.panels_flow \
+    #     innerPadding: { x: 5, y: 5 },
+    #     childViews: ->(flow) do
+    #       @tags.each do |tag|
+    #         flow.chip text: tag.name
+    #       end
+    #     end
+    #
+    # @see app/views/json_ui/garage/panels/flow.json.jbuilder Garage examples
     class Flow < View
+      # Padding applied to each child element wrapper.
+      # Different from the panel's own padding - this creates gaps between items.
+      # @example innerPadding: { x: 10, y: 10 }
+      # @example innerPadding: { top: 5, right: 10, bottom: 5, left: 10 }
       hash :innerPadding, optional: [:top, :right, :bottom, :left, :x, :y]
 
+      # Configuration for xxl breakpoint (> 2560px).
+      # @example xxl: { gap: { all: 32 }, padding: { all: 48 } }
       hash :xxl, optional: [:gap, :padding]
+
+      # Configuration for xl breakpoint (1904px - 2560px).
+      # @example xl: { gap: { x: 24, y: 24 } }
       hash :xl, optional: [:gap, :padding]
+
+      # Configuration for lg breakpoint (1264px - 1904px).
+      # @example lg: { gap: { all: 16 }, padding: { x: 30, y: 30 } }
       hash :lg, optional: [:gap, :padding]
+
+      # Configuration for md breakpoint (960px - 1264px).
+      # @example md: { gap: { y: 8, x: 8 } }
       hash :md, optional: [:gap, :padding]
+
+      # Configuration for sm breakpoint (600px - 960px).
+      # @example sm: { gap: { y: 4, x: 6 }, padding: { all: 16 } }
       hash :sm, optional: [:gap, :padding]
+
+      # Configuration for xs breakpoint (< 600px).
+      # @example xs: { gap: { y: 2, x: 2 }, padding: { left: 10, bottom: 8 } }
       hash :xs, optional: [:gap, :padding]
 
+      # Child components to arrange in flow layout.
       views :childViews
 
-      string :align
+      # Vertical alignment of children within each row.
+      # @example align: 'middle'
+      enum :align, options: [:top, :middle, :bottom]
 
       # required :innerPadding
     end

data/app/helpers/glib/json_ui/view_builder.rb

@@ -7,7 +7,7 @@ module Glib
       included do
         string :directUploadUrl
         hash :accepts, optional: [:fileType, :maxFileSize, :maxFileLength, :maxFileSizeErrorText, :maxFileLengthErrorText]
-        string :strategy # can be "delegate" or "dropUpload"
+        enum :strategy, options: [:delegate, :dropUpload]
         string :storagePrefix
         hash :metadata
         string :tagging