terrazzo 0.6.0 → 0.7.0

data/lib/generators/terrazzo/views/templates/pages/_form.jsx

@@ -1,10 +1,39 @@
 import React from "react";
 
-import { FieldRenderer } from "terrazzo/fields";
-import { Button } from "terrazzo/ui";
+import { FieldRenderer } from "../fields";
+import { Button } from "../components/ui";
 
-export function AdminForm({ form, errors }) {
-  const { props: formProps, extras, fieldGroups, fields } = form;
+export function AdminForm({ form = {}, errors = [] }) {
+  const { props: formProps = {}, extras = {}, fieldGroups = [], fields = [] } = form;
+  const groups = Array.isArray(fieldGroups) ? fieldGroups : [];
+  const hasFieldGroups = groups.length > 0;
+
+  const renderField = (field) => {
+    const hintId = field.hint && field.input?.id ? `${field.input.id}_hint` : null;
+    const input = hintId ?
+      { ...field.input, "aria-describedby": hintId } :
+      field.input;
+
+    return (
+      <div key={field.attribute} className="space-y-2">
+        <FieldRenderer
+          mode="form"
+          fieldType={field.fieldType}
+          value={field.value}
+          options={field.options}
+          attribute={field.attribute}
+          label={field.label}
+          hint={field.hint}
+          input={input}
+          required={field.required} />
+        {field.hint && (
+          <p id={hintId ?? undefined} className="text-sm text-muted-foreground">
+            {field.hint}
+          </p>
+        )}
+      </div>
+    );
+  };
 
   return (
     <>
@@ -26,44 +55,22 @@ export function AdminForm({ form, errors }) {
         <input key={hiddenProps.name} {...hiddenProps} />
         )}
 
-        {fieldGroups ? (
+        {hasFieldGroups ? (
           <div className="space-y-8">
-            {fieldGroups.map((group, groupIndex) =>
+            {groups.map((group, groupIndex) =>
               <fieldset key={groupIndex} className="space-y-6">
                 {group.name && (
                   <legend className="text-lg font-semibold">{group.name}</legend>
                 )}
                 <div className="space-y-6">
-                  {group.fields.map((field) =>
-                    <FieldRenderer
-                      key={field.attribute}
-                      mode="form"
-                      fieldType={field.fieldType}
-                      value={field.value}
-                      options={field.options}
-                      attribute={field.attribute}
-                      label={field.label}
-                      input={field.input}
-                      required={field.required} />
-                  )}
+                  {(group.fields || []).map((field) => renderField(field))}
                 </div>
               </fieldset>
             )}
           </div>
         ) : (
           <div className="space-y-6">
-            {fields.map((field) =>
-            <FieldRenderer
-              key={field.attribute}
-              mode="form"
-              fieldType={field.fieldType}
-              value={field.value}
-              options={field.options}
-              attribute={field.attribute}
-              label={field.label}
-              input={field.input}
-              required={field.required} />
-            )}
+            {fields.map((field) => renderField(field))}
           </div>
         )}
 

data/lib/generators/terrazzo/views/templates/pages/_navigation.json.props

@@ -1,5 +1,15 @@
-json.array! Terrazzo::Namespace.new(namespace).resources_with_index_route do |nav_resource|
-  json.label nav_resource.resource_name.humanize.pluralize
-  json.path url_for(controller: "/#{nav_resource.controller_path}", action: :index, only_path: true)
-  json.active nav_resource.controller_path == controller_path
+resources = Terrazzo::Namespace.new(namespace).navigation_resources
+navigation_groups = resources.group_by(&:navigation_group).map do |label, items|
+  { label: label, items: items }
+end
+
+json.array! navigation_groups do |group|
+  json.label group[:label]
+  json.items do
+    json.array! group[:items] do |nav_resource|
+      json.label nav_resource.navigation_label
+      json.path url_for(controller: "/#{nav_resource.controller_path}", action: :index, only_path: true)
+      json.active nav_resource.controller_path == controller_path
+    end
+  end
 end

data/lib/generators/terrazzo/views/templates/pages/edit.jsx

@@ -3,7 +3,8 @@ import { useContent } from "@thoughtbot/superglue";
 
 import { getLayout } from "terrazzo";
 import { AdminForm } from "./_form";
-import { Button, Card, CardContent } from "terrazzo/ui";
+import { CollectionToolbarActions } from "../components";
+import { Button, Card, CardContent } from "../components/ui";
 
 export default function AdminEdit() {
   const Layout = getLayout();
@@ -11,10 +12,10 @@ export default function AdminEdit() {
     pageTitle,
     form,
     errors,
+    layoutActions,
     indexPath,
     showPath,
-    navigation,
-    resourceName
+    navigation
   } = useContent();
 
   return (
@@ -22,7 +23,8 @@ export default function AdminEdit() {
       navigation={navigation}
       title={pageTitle}
       actions={
-      <div className="flex gap-2">
+      <div className="flex flex-wrap items-center gap-2">
+          <CollectionToolbarActions actions={layoutActions} />
           {showPath &&
         <a href={showPath} data-sg-visit>
               <Button variant="outline" size="sm">Cancel</Button>

data/lib/generators/terrazzo/views/templates/pages/index.jsx

@@ -2,16 +2,21 @@ import React from "react";
 import { useContent } from "@thoughtbot/superglue";
 
 import { getLayout } from "terrazzo";
-import { SearchBar, Pagination } from "terrazzo/components";
+import { SearchBar, CollectionFilters, Pagination, CollectionToolbarActions } from "../components";
 import { AdminCollection } from "./_collection";
-import { Button } from "terrazzo/ui";
+import { Button } from "../components/ui";
 
 export default function AdminIndex() {
   const Layout = getLayout();
   const {
     table,
     searchBar,
+    filters,
     pagination,
+    layoutActions,
+    toolbarActions,
+    bulkActions,
+    emptyState,
     navigation,
     newResourcePath,
     resourceName,
@@ -22,17 +27,24 @@ export default function AdminIndex() {
     <Layout
       navigation={navigation}
       title={resourceName}
-      actions={newResourcePath &&
-      <a href={newResourcePath} data-sg-visit>
-          <Button size="sm">New {singularResourceName}</Button>
-        </a>
+      actions={
+        <div className="flex flex-wrap items-center gap-2">
+          <CollectionToolbarActions actions={layoutActions} />
+          <CollectionToolbarActions actions={toolbarActions} />
+          {newResourcePath && (
+            <a href={newResourcePath} data-sg-visit>
+              <Button size="sm">New {singularResourceName}</Button>
+            </a>
+          )}
+        </div>
       }>
 
-      <div className="flex items-center">
+      <div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
         <SearchBar {...searchBar} />
+        <CollectionFilters {...filters} />
       </div>
 
-      <AdminCollection table={table} />
+      <AdminCollection table={table} emptyState={emptyState} bulkActions={bulkActions} />
 
       <Pagination {...pagination} />
     </Layout>);

data/lib/generators/terrazzo/views/templates/pages/new.jsx

@@ -3,7 +3,8 @@ import { useContent } from "@thoughtbot/superglue";
 
 import { getLayout } from "terrazzo";
 import { AdminForm } from "./_form";
-import { Button, Card, CardContent } from "terrazzo/ui";
+import { CollectionToolbarActions } from "../components";
+import { Button, Card, CardContent } from "../components/ui";
 
 export default function AdminNew() {
   const Layout = getLayout();
@@ -11,9 +12,9 @@ export default function AdminNew() {
     pageTitle,
     form,
     errors,
+    layoutActions,
     indexPath,
-    navigation,
-    resourceName
+    navigation
   } = useContent();
 
   return (
@@ -21,9 +22,12 @@ export default function AdminNew() {
       navigation={navigation}
       title={pageTitle}
       actions={
-      <a href={indexPath} data-sg-visit>
+      <div className="flex flex-wrap items-center gap-2">
+        <CollectionToolbarActions actions={layoutActions} />
+        <a href={indexPath} data-sg-visit>
           <Button variant="outline" size="sm">Cancel</Button>
         </a>
+      </div>
       }>
 
       <Card>

data/lib/generators/terrazzo/views/templates/pages/show.jsx

@@ -2,8 +2,9 @@ import React from "react";
 import { useContent } from "@thoughtbot/superglue";
 
 import { getLayout } from "terrazzo";
-import { FieldRenderer } from "terrazzo/fields";
-import { Button, Card, CardContent, CardHeader, CardTitle } from "terrazzo/ui";
+import { FieldRenderer } from "../fields";
+import { CollectionToolbarActions } from "../components";
+import { Card, CardContent, CardHeader, CardTitle } from "../components/ui";
 
 export default function AdminShow() {
   const Layout = getLayout();
@@ -11,47 +12,41 @@ export default function AdminShow() {
     pageTitle,
     attributes,
     attributeGroups,
+    layoutActions,
     editPath,
     deletePath,
     indexPath,
-    resourceName,
     pluralResourceName,
     navigation
   } = useContent();
+  const resourceActions = [
+    indexPath && {
+      label: `Back to ${pluralResourceName}`,
+      url: indexPath,
+      variant: "outline",
+    },
+    editPath && {
+      label: "Edit",
+      url: editPath,
+      variant: "outline",
+    },
+    deletePath && {
+      label: "Delete",
+      url: deletePath,
+      method: "delete",
+      confirm: "Are you sure?",
+      variant: "destructive",
+    },
+  ].filter(Boolean);
 
   return (
     <Layout
       navigation={navigation}
       title={pageTitle}
       actions={
-      <div className="flex gap-2">
-          <a href={indexPath} data-sg-visit>
-            <Button variant="outline" size="sm">Back to {pluralResourceName}</Button>
-          </a>
-          {editPath &&
-        <a href={editPath} data-sg-visit>
-              <Button variant="outline" size="sm">Edit</Button>
-            </a>
-        }
-          {deletePath &&
-        <form
-          action={deletePath}
-          method="post"
-          data-sg-visit
-          style={{ display: "inline" }}
-          onSubmit={(e) => {
-            if (!window.confirm("Are you sure?")) e.preventDefault();
-          }}>
-
-              <input type="hidden" name="_method" value="delete" />
-              <input
-            type="hidden"
-            name="authenticity_token"
-            value={document.querySelector('meta[name="csrf-token"]')?.content ?? ""} />
-
-              <Button type="submit" variant="destructive" size="sm">Delete</Button>
-            </form>
-        }
+      <div className="flex flex-wrap items-center gap-2">
+          <CollectionToolbarActions actions={layoutActions} />
+          <CollectionToolbarActions actions={resourceActions} />
         </div>
       }>
 
@@ -69,7 +64,10 @@ export default function AdminShow() {
                 return (
                   <div key={key} className="py-4 grid grid-cols-3 gap-4">
                     <dt className="text-sm font-medium text-muted-foreground">
-                      {attr.label}
+                      <span>{attr.label}</span>
+                      {attr.hint && (
+                        <p className="mt-1 font-normal">{attr.hint}</p>
+                      )}
                     </dt>
                     <dd className="col-span-2 text-sm">
                       {attr.showPath ? (

data/lib/generators/terrazzo/views/views_generator.rb

@@ -27,20 +27,24 @@ module Terrazzo
       def create_ui_barrel
         create_file "app/views/#{namespace_name}/components/ui/index.js", <<~JS
           // Re-export all UI primitives from the terrazzo package.
-          // To customize, run: rails g terrazzo:eject ui/<component_name>
+          // Ejected pages, fields, and components import this barrel.
+          // To customize those app-owned files, run: rails g terrazzo:eject ui/<component_name>
           export * from "terrazzo/ui";
         JS
       end
 
       def create_navigation_partial
         create_file "app/views/#{namespace_name}/application/_navigation.json.props", <<~RUBY
-          resources = Terrazzo::Namespace.new(namespace).resources_with_index_route
+          resources = Terrazzo::Namespace.new(namespace).navigation_resources
+          navigation_groups = resources.group_by(&:navigation_group).map do |label, items|
+            { label: label, items: items }
+          end
 
-          json.array! [{ label: "Resources", resources: resources }] do |group|
+          json.array! navigation_groups do |group|
             json.label group[:label]
             json.items do
-              json.array! group[:resources] do |r|
-                json.label r.resource_name.humanize.pluralize
+              json.array! group[:items] do |r|
+                json.label r.navigation_label
                 json.path url_for(controller: "/\#{r.controller_path}", action: :index, only_path: true)
                 json.active r.controller_path == controller_path
               end

data/lib/terrazzo/base_dashboard.rb

@@ -1,3 +1,5 @@
+require "set"
+
 module Terrazzo
   class BaseDashboard
     Field = Terrazzo::Field
@@ -66,16 +68,41 @@ module Terrazzo
       "#{resource.class.name} ##{resource.id}"
     end
 
+    def attribute_label(attribute, _context = nil)
+      attribute.to_s.humanize
+    end
+
+    def attribute_hint(_attribute, _context = nil)
+      nil
+    end
+
+    def collection_cell_options(_attribute, _resource)
+      {}
+    end
+
+    def collection_header_options(_attribute)
+      {}
+    end
+
+    def collection_row_options(_resource)
+      {}
+    end
+
     def collection_includes
-      collection_attr_set = Set.new(collection_attributes)
+      includes_for_attributes(collection_attributes)
+    end
+
+    def includes_for_attributes(attributes)
+      attribute_set = Set.new(flatten_attributes(attributes))
       model = self.class.model
       attribute_types.each_with_object([]) do |(attr, type), includes|
-        next unless collection_attr_set.include?(attr)
+        next unless attribute_set.include?(attr)
         next unless type.eager_load?
-        has_association = model.reflect_on_association(attr)
-        has_attachment = model.respond_to?(:reflect_on_attachment) && model.reflect_on_attachment(attr)
+        include_target = type.eager_load_association(attr, model)
+        has_association = model.reflect_on_association(include_target)
+        has_attachment = model.respond_to?(:reflect_on_attachment) && model.reflect_on_attachment(include_target)
         next unless has_association || has_attachment
-        includes << attr
+        includes << include_target
       end
     end
 
@@ -84,6 +111,141 @@ module Terrazzo
       self.class::COLLECTION_FILTERS
     end
 
+    def collection_filter_options(_view = nil)
+      collection_filters.filter_map do |name, filter|
+        next if filter.respond_to?(:arity) && filter.arity > 1
+
+        {
+          label: collection_filter_label(name),
+          value: name.to_s,
+        }
+      end
+    end
+
+    def collection_filter_label(filter_name)
+      filter_name.to_s.humanize
+    end
+
+    def collection_item_actions(resource, view = nil)
+      return [] unless view
+
+      actions = []
+      if (path = view.collection_action_path(resource, :show))
+        actions << { label: "Show", url: path }
+      end
+      if (path = view.collection_action_path(resource, :edit))
+        actions << { label: "Edit", url: path }
+      end
+      if (path = view.collection_action_path(resource, :destroy))
+        actions << {
+          label: "Destroy",
+          url: path,
+          method: "delete",
+          confirm: "Are you sure?"
+        }
+      end
+      actions
+    end
+
+    def collection_toolbar_actions(view = nil)
+      return [] unless view && csv_export_enabled?
+
+      [
+        {
+          label: "Export CSV",
+          url: csv_export_url(view),
+          sg_visit: false,
+        },
+      ]
+    end
+
+    def collection_bulk_actions(_view = nil)
+      []
+    end
+
+    def layout_actions(_page, _view = nil, resource: nil)
+      []
+    end
+
+    def csv_export_enabled?
+      true
+    end
+
+    def csv_attributes
+      collection_attributes
+    end
+
+    def csv_filename
+      "#{self.class.resource_name.pluralize.parameterize}.csv"
+    end
+
+    def csv_value(_attribute, value, _resource)
+      case value
+      when nil
+        nil
+      when Hash
+        csv_hash_value(value)
+      when Array
+        value.map { |item| csv_value(nil, item, nil) }.join(", ")
+      else
+        value.to_s
+      end
+    end
+
+    def empty_collection_message
+      "No #{self.class.resource_name.pluralize.downcase} match the current view."
+    end
+
+    def navigation_label
+      self.class.const_defined?(:NAVIGATION_LABEL, false) ?
+        self.class::NAVIGATION_LABEL :
+        self.class.resource_name.pluralize
+    end
+
+    def navigation_group
+      self.class.const_defined?(:NAVIGATION_GROUP, false) ?
+        self.class::NAVIGATION_GROUP :
+        default_navigation_group
+    end
+
+    def navigation_order
+      self.class.const_defined?(:NAVIGATION_ORDER, false) ?
+        self.class::NAVIGATION_ORDER :
+        navigation_label
+    end
+
+    def navigation_group_order
+      self.class.const_defined?(:NAVIGATION_GROUP_ORDER, false) ?
+        self.class::NAVIGATION_GROUP_ORDER :
+        navigation_group
+    end
+
+    def show_in_navigation?
+      self.class.const_defined?(:SHOW_IN_NAVIGATION, false) ?
+        self.class::SHOW_IN_NAVIGATION :
+        true
+    end
+
+    private
+
+    def default_navigation_group
+      model_namespace = self.class.model.name.deconstantize
+      model_namespace.present? ? model_namespace.underscore.humanize.titleize : "Resources"
+    end
+
+    def csv_export_url(view)
+      query = view.request.query_parameters.except("_page", "per_page")
+      view.url_for(query.merge(format: :csv, only_path: true))
+    end
+
+    def csv_hash_value(value)
+      indifferent = value.with_indifferent_access
+      return indifferent[:display].to_s if indifferent.key?(:display)
+      return "#{indifferent[:count]} #{indifferent[:label]}" if indifferent.key?(:count) && indifferent.key?(:label)
+
+      JSON.generate(value)
+    end
+
     class << self
       def model
         name.chomp("Dashboard").constantize

data/lib/terrazzo/csv_export.rb

@@ -0,0 +1,38 @@
+require "csv"
+require "json"
+
+module Terrazzo
+  class CsvExport
+    attr_reader :dashboard, :resources
+
+    def initialize(dashboard, resources)
+      @dashboard = dashboard
+      @resources = resources
+    end
+
+    def to_csv
+      CSV.generate(headers: true) do |csv|
+        csv << attributes.map { |attr| header_for(attr) }
+
+        resources.each do |resource|
+          csv << attributes.map { |attr| value_for(resource, attr) }
+        end
+      end
+    end
+
+    private
+
+    def attributes
+      @attributes ||= dashboard.flatten_attributes(dashboard.csv_attributes)
+    end
+
+    def header_for(attribute)
+      dashboard.attribute_label(attribute, :csv)
+    end
+
+    def value_for(resource, attribute)
+      field = dashboard.attribute_type_for(attribute).new(attribute, nil, :index, resource: resource)
+      dashboard.csv_value(attribute, field.serialize_value(:index), resource)
+    end
+  end
+end

data/lib/terrazzo/field/associative.rb

@@ -14,6 +14,13 @@ module Terrazzo
       private
 
       def display_name(record)
+        dashboard = dashboard_for(record.class)
+        return dashboard.display_resource(record) if dashboard && custom_display_resource?(dashboard)
+
+        fallback_display_name(record)
+      end
+
+      def fallback_display_name(record)
         if record.respond_to?(:display_name)
           record.display_name
         elsif record.respond_to?(:name)
@@ -44,16 +51,21 @@ module Terrazzo
           associated_class.all
         end
         pk = association_primary_key
-        dashboard = associated_dashboard
-        scope.map { |r| [dashboard ? dashboard.display_resource(r) : display_name(r), r.public_send(pk).to_s] }
+        scope.map { |r| [display_name(r), r.public_send(pk).to_s] }
       end
 
-      def associated_dashboard
-        "#{associated_class.name}Dashboard".constantize.new
+      def dashboard_for(klass)
+        return nil unless klass
+
+        "#{klass.name}Dashboard".constantize.new
       rescue NameError
         nil
       end
 
+      def custom_display_resource?(dashboard)
+        dashboard.method(:display_resource).owner != Terrazzo::BaseDashboard
+      end
+
       def association_primary_key
         reflection = resource&.class&.reflect_on_association(attribute)
         reflection&.association_primary_key || :id

data/lib/terrazzo/field/base.rb

@@ -83,6 +83,10 @@ module Terrazzo
           false
         end
 
+        def eager_load_association(attr, _model_class = nil)
+          attr.to_sym
+        end
+
         def associative?
           false
         end

data/lib/terrazzo/field/belongs_to.rb

@@ -46,8 +46,7 @@ module Terrazzo
         end
         scope = scope.reorder(options[:order]) if options[:order]
         pk = association_primary_key
-        dashboard = associated_dashboard
-        scope.map { |r| [dashboard ? dashboard.display_resource(r) : display_name(r), r.public_send(pk).to_s] }
+        scope.map { |r| [display_name(r), r.public_send(pk).to_s] }
       end
 
       def foreign_key_value

data/lib/terrazzo/field/deferred.rb

@@ -30,6 +30,10 @@ module Terrazzo
         deferred_class.eager_load?
       end
 
+      def eager_load_association(attr, model_class = nil)
+        deferred_class.eager_load_association(attr, model_class)
+      end
+
       def associative?
         deferred_class.associative?
       end