@wix/auto-patterns 1.15.0 → 1.17.0

package/dist/docs/app_config_structure.md

@@ -0,0 +1,356 @@
+# AppConfig Structure
+
+## ⚠️ Configuration Rules
+
+- **Configuration must come only from a JSON file** - never inline or from other sources
+- **DO NOT fill optional fields unless explicitly requested** - leave optional properties undefined to avoid unnecessary complexity
+- **After each configuration change, verify that the configuration strictly aligns with the structure described below** - any configuration entries not defined in this structure must be removed
+- **When generating config for the first time, select up to 3 columns from the schema that best represent the entity**
+
+## ⚠️ Common Configuration Mistakes to Avoid
+
+- Adding more than two pages
+- Mixing page types in a single configuration
+- Including undefined optional fields
+- Selecting too many initial columns
+- Not designating exactly one page as `appMainPage: true`
+- Missing or inconsistent page relationships (parentPageId/entityPageId)
+- Setting `stickyColumns` to invalid values (negative, zero, or exceeding column count)
+
+```ts
+export interface AppConfig {
+  pages: {
+    id: string; // Page unique identifier (must be unique across the app)
+    type: 'collectionPage' | 'entityPage'; // Defines page type
+    appMainPage?: boolean; // Designates this page as the main page (exactly one page must have this set to true)
+    collectionPage?: {
+      route: {
+        path: string; // Route path for the collection page (e.g., '/')
+      };
+      title: {
+        text: string; // Main page title
+        hideTotal?: boolean; // Hide total items in header. Default: true
+      };
+      subtitle?: {
+        text: string; // Optional page subtitle
+      };
+      actions?: { // Defines page-level actions for the collection page
+        primaryActions?: {
+          type: 'action' | 'menu'; // Type of primary actions layout
+          action?: { // Required when type is 'action'
+            item: {
+              id: string; // Unique identifier for the action
+              type: 'create' | 'custom'; // Action type
+              label?: string; // Text displayed for the action
+              collection: {
+                collectionId: string; // ID of the Wix Data collection
+                entityTypeSource: 'cms'; // Data source type. Always 'cms'
+              };
+              create?: { // Required when type is 'create'
+                mode: 'page'; // Create mode
+                page: {
+                  id: string; // Entity page ID to navigate to for creation
+                };
+              };
+            };
+          };
+          menu?: { // Required when type is 'menu'
+            label: string; // Label for the group
+            items: {}[]; // Array of action configurations, same structure as action.item, can include dividers
+          };
+        };
+        secondaryActions?: {
+          type: 'action' | 'menu'; // Type of secondary actions layout, same structure as primaryActions
+          action?: {}; // Same structure as primaryActions.action
+          menu?: {}; // Same structure as primaryActions.menu
+        };
+      };
+      components: [
+        {
+          entityPageId?: string; // ID of the entity page to navigate to when clicking a row
+          collection: {
+            collectionId: string; // ID of the Wix Data collection
+            entityTypeSource: 'cms'; // Data source type. Always 'cms'
+            reflectQueryInUrl?: boolean; // Reflects query state (search, filters, sorting) in the browser URL. Default: false
+            selectAllScope?: 'page' | 'all'; // Controls "Select All" scope. 'all' selects entire collection, 'page' selects only visible items. Default: 'all'
+            selectionUpdateMode?: 'preserve' | 'clear'; // Controls selection behavior when data changes. 'preserve' maintains selections, 'clear' clears them. Default: 'clear'
+          };
+          filters?: {
+            panelTitle?: string; // Title of the filters panel
+            items: {
+              id: string; // Unique identifier for the filter item
+              fieldId: string; // ID of the field to filter by (must be a valid type: NUMBER, DATETIME, BOOLEAN, ARRAY, ARRAY_STRING)
+              displayName?: string; // Display name of the filter item
+              openByDefault?: boolean; // Whether the filter item is open by default in the panel (accordion is open)
+              sectionTitle?: string; // Title of the filter section. Required if more than one section exists to prevent confusion
+              tagLabel?: string; // Label shown in Tag component in the table/grid when the filter is applied (e.g., "Age: 7")
+              numberConfig?: {
+                min?: number; // Minimum value
+                max?: number; // Maximum value
+                allowedDecimals?: true; // Decimal precision allowed
+              };
+              dateConfig?: {
+                mode?: 'ONLY_PREDEFINED' | 'ONLY_CUSTOM' | 'COMBINE'; // Determines filter behavior
+                presets?: (
+                  | 'SEVEN_DAYS'
+                  | 'FOURTEEN_DAYS'
+                  | 'MONTH'
+                  | 'TODAY'
+                  | 'TOMORROW'
+                  | 'NEXT_THREE_DAYS'
+                  | 'NEXT_SEVEN_DAYS'
+                  | 'NEXT_THIRTY_DAYS'
+                )[]; // Shown only if mode includes predefined presets (COMBINE or ONLY_PREDEFINED)
+                includeTime?: boolean; // Whether to allow time selection. Default is true
+              };
+              booleanConfig?: {
+                trueLabel?: string; // Label shown for the true value
+                falseLabel?: string; // Label shown for the false value
+              };
+              enumConfig?: {
+                options: {
+                  value: string; // Enum option value
+                  label: string; // Enum option label
+                }[];
+                selectionMode: 'single' | 'multiple'; // Selection behavior
+                optionType?:
+                  | 'checkbox'
+                  | 'inlineCheckbox'
+                  | 'radio'
+                  | 'select'; // Option rendering style
+              };
+            }[];
+          };
+          actionCell?: {
+            primaryAction?: {
+              item: {
+                id: string; // Unique identifier for the action
+                type: 'update' | 'delete' | 'custom'; // Action type
+                label?: string; // Text displayed for the action
+                skin?: string; // Visual appearance of the action button (see Action Button Skin Values section)
+                disabled?: boolean; // Whether the action is disabled
+                tooltip?: string; // Tooltip text shown on hover
+                update?: { // Required when type is 'update'
+                  mode: 'page'; // Update mode
+                  page?: { // Required when mode is 'page'
+                    id: string; // Entity page ID to navigate to
+                  };
+                };
+                delete?: { // Required when type is 'delete'
+                  mode: 'modal'; // Currently only 'modal' is supported
+                  modal: {
+                    title?: {
+                      text: string; // Modal title
+                    };
+                    description?: {
+                      text: string; // Modal description
+                    };
+                    actions?: {
+                      submit?: {
+                        text: string; // Submit button text
+                      };
+                      cancel?: {
+                        text: string; // Cancel button text
+                      };
+                    };
+                    feedback?: {
+                      successToast?: {
+                        text: string; // Success message
+                      };
+                      errorToast?: {
+                        text: string; // Error message
+                      };
+                    };
+                  };
+                };
+              };
+            };
+            secondaryActions?: {
+              items: {}[]; // Array of action configurations, same structure as primaryAction.item, can include dividers
+              inlineCount?: number; // How many secondary actions to show inline before showing popover
+              inlineAlwaysVisible?: boolean; // Whether to always show inline actions (not just on hover)
+            };
+          };
+          bulkActionToolbar?: {
+            primaryActions?: ({
+              type: 'action' | 'menu'; // Type of bulk action item
+              action?: { // Required when type is 'action'
+                item: {
+                  id: string; // Unique identifier for the bulk action
+                  type: 'bulkDelete' | 'custom'; // Bulk action type
+                  label?: string; // Text displayed for the action
+                  bulkDelete?: { // Required when type is 'bulkDelete'
+                    mode: 'modal'; // Currently only 'modal' is supported
+                    modal: {
+                      title?: {
+                        text: string; // Modal title
+                      };
+                      description?: {
+                        text: string; // Modal description
+                      };
+                      actions?: {
+                        submit?: {
+                          text: string; // Submit button text
+                        };
+                        cancel?: {
+                          text: string; // Cancel button text
+                        };
+                      };
+                      feedback?: {
+                        successToast?: {
+                          text: string; // Success message
+                        };
+                        errorToast?: {
+                          text: string; // Error message
+                        };
+                      };
+                    };
+                  };
+                };
+              };
+              menu?: { // Required when type is 'menu'
+                label: string; // Label for the dropdown group
+                items: {}[] // Array of bulk actions configurations, same structure as action.item, can include dividers
+              };
+            })[];
+            secondaryActions?: {}[]; // Array of bulk actions configurations, same structure as primaryActions[].menu.items, can include dividers
+          };
+          toolbarTitle?: {
+            title: string; // Toolbar title above the table/grid
+            subtitle?: {
+              text: string; // Toolbar subtitle
+            };
+            showTotal?: boolean; // Show total items on toolbar. Default: false
+          };
+          search?: {
+            shown?: boolean; // Show/hide the search
+          };
+          emptyState?: {
+            title?: string; // Empty state title
+            subtitle?: string; // Empty state subtitle
+            image?: {
+              id: string; // Image ID for empty state
+            };
+            addNewCta?: {
+              id?: string; // Add New CTA ID
+              text?: string; // Add New CTA text
+            };
+            customCta?: {
+              id?: string; // Custom CTA ID
+            };
+          };
+          layout: [ // Array of layout items that define what components to render
+            {
+              type: 'Table'; // Layout item type for table rendering
+              table?: {
+                columns: {
+                  id: string; // Field ID from the collection
+                  name: string; // Column title displayed
+                  width: string; // The width of the column (required in types)
+                  sortable?: boolean; // If the column is sortable
+                  defaultSortOrder?: 'asc' | 'desc'; // Optional default sort order
+                  sortMode?: 'asc' | 'desc'; // Optional sorting mode
+                  reorderDisabled?: boolean; // Whether column reordering is disabled
+                  hideable?: boolean; // Whether column can be hidden
+                  defaultHidden?: boolean; // Whether column is hidden by default
+                  hiddenFromCustomColumnsSelection?: boolean; // Whether column is hidden from custom columns selection
+                }[];
+                customColumns?: {
+                  enabled: boolean; // Enable user customization (hide/reorder columns)
+                };
+                stickyColumns?: number; // Number of columns to make sticky from the start. Sticky columns remain visible when horizontally scrolling.
+              };
+            },
+            {
+              type: 'Grid'; // Layout item type for grid rendering
+              grid?: {
+                item: {
+                  titleFieldId: string; // Field ID to display as the item title
+                  subtitleFieldId?: string; // Field ID for the item subtitle
+                  imageFieldId?: string; // Field ID for the item image
+                  /**
+                   * Controls which content is shown in the card (preset):
+                   * - 'full': Shows both title and subtitle.
+                   * - 'title': Shows only the title.
+                   * - 'empty': Hides both title and subtitle (card appears visually empty except for image or other content).
+                   */
+                  cardContentMode?: 'full' | 'title' | 'empty';
+                  imagePlacement?: 'top' | 'side';
+                };
+              };
+            }
+          ]; // End of layout array
+        }
+      ]; // End of components array
+    };
+    entityPage?: {
+      route: {
+        path: string; // Route path for the entity page (e.g., '/product/:entityId')
+        params: {
+          id: string; // Maps dynamic parameter in path to its identifier
+        };
+      };
+      title?: {
+        text: string; // Entity page title
+      };
+      subtitle?: {
+        text: string; // Entity page subtitle
+      };
+      parentPageId?: string; // ID of the parent collection page
+      layout?: {
+        // Main layout section
+        main: {
+          type: 'card'; // Type of the card
+          card: {
+            title: {
+              text: string; // Title of the card
+            };
+            subtitle?: {
+              text: string; // Subtitle of the card
+            };
+            children: LayoutContent[]; // Array of content items that can be fields, nested containers, or components
+          };
+        }[];
+        // Sidebar layout section
+        sidebar?: {
+          type: 'card';
+          card: {
+            title: {
+              text: string; // Title of the card
+            };
+            subtitle?: {
+              text: string; // Subtitle of the card
+            };
+            children: LayoutContent[]; // Array of content items that can be fields, nested containers, or components
+          };
+        }[];
+      };
+      collectionId: string; // Related collection ID
+      entityTypeSource: 'cms'; // Data source type. Always 'cms'
+    };
+  }[];
+}
+
+type LayoutContent =
+  | {
+      type: 'field';
+      field: {
+        span?: number;
+        fieldId: string;
+      };
+    }
+  | {
+      type: 'container';
+      container: {
+        span?: number;
+        children: LayoutContent[];
+      };
+    }
+  | {
+      type: 'component';
+      component: {
+        span?: number;
+        componentId: string;
+      };
+    };
+```