plutonium 0.15.5 → 0.15.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. checksums.yaml +4 -4
  2. data/app/assets/plutonium.css +1 -1
  3. data/app/assets/plutonium.ico +0 -0
  4. data/app/assets/plutonium.png +0 -0
  5. data/docs/.vitepress/config.ts +61 -0
  6. data/docs/.vitepress/theme/custom.css +61 -0
  7. data/docs/.vitepress/theme/index.ts +4 -0
  8. data/docs/api-examples.md +49 -0
  9. data/docs/guide/getting-started/authorization.md +296 -0
  10. data/docs/guide/getting-started/core-concepts.md +432 -0
  11. data/docs/guide/getting-started/index.md +18 -0
  12. data/docs/guide/getting-started/installation.md +269 -0
  13. data/docs/guide/getting-started/resources.md +254 -0
  14. data/docs/guide/what-is-plutonium.md +211 -0
  15. data/docs/index.md +43 -0
  16. data/docs/markdown-examples.md +85 -0
  17. data/docs/public/android-chrome-192x192.png +0 -0
  18. data/docs/public/android-chrome-512x512.png +0 -0
  19. data/docs/public/apple-touch-icon.png +0 -0
  20. data/docs/public/favicon-16x16.png +0 -0
  21. data/docs/public/favicon-32x32.png +0 -0
  22. data/docs/public/favicon.ico +0 -0
  23. data/docs/public/plutonium.png +0 -0
  24. data/docs/public/site.webmanifest +1 -0
  25. data/docs/public/templates/plutonium.rb +21 -0
  26. data/lib/generators/pu/core/assets/assets_generator.rb +2 -3
  27. data/lib/generators/pu/core/assets/templates/tailwind.config.js +2 -2
  28. data/lib/generators/pu/core/install/install_generator.rb +9 -1
  29. data/lib/generators/pu/core/install/templates/config/initializers/plutonium.rb +0 -1
  30. data/lib/plutonium/core/controllers/authorizable.rb +1 -1
  31. data/lib/plutonium/railtie.rb +0 -10
  32. data/lib/plutonium/resource/controllers/crud_actions.rb +1 -1
  33. data/lib/plutonium/resource/policy.rb +4 -5
  34. data/lib/plutonium/resource/register.rb +3 -0
  35. data/lib/plutonium/ui/action_button.rb +34 -19
  36. data/lib/plutonium/ui/form/resource.rb +2 -1
  37. data/lib/plutonium/ui/table/components/search_bar.rb +1 -1
  38. data/lib/plutonium/version.rb +1 -1
  39. data/package-lock.json +5767 -1851
  40. data/package.json +10 -4
  41. data/src/js/core.js +0 -1
  42. data/tailwind.options.js +89 -11
  43. metadata +27 -11
  44. data/app/assets/plutonium-original.png +0 -0
  45. data/app/assets/plutonium-white.png +0 -0
  46. data/public/plutonium-assets/fonts/bootstrap-icons.woff +0 -0
  47. data/public/plutonium-assets/fonts/bootstrap-icons.woff2 +0 -0
  48. /data/{templates → docs/public/templates}/base.rb +0 -0
@@ -0,0 +1,254 @@
1
+ # Working with Resources
2
+
3
+ ::: tip What you'll learn
4
+ - How to create and manage resources in Plutonium
5
+ - Understanding resource definitions and configurations
6
+ - Working with fields, associations, and nested resources
7
+ - Implementing resource policies and scoping
8
+ - Best practices for resource organization
9
+ :::
10
+
11
+ ## Introduction
12
+
13
+ Resources are the core building blocks of a Plutonium application. A resource represents a model in your application that can be managed through a consistent interface, complete with views, controllers, and policies.
14
+
15
+ ## Creating a Resource
16
+
17
+ The fastest way to create a resource is using the scaffold generator:
18
+
19
+ ```bash
20
+ rails generate pu:res:scaffold Blog user:belongs_to title:string content:text state:string published_at:datetime?
21
+ ```
22
+
23
+ This generates several files, including:
24
+
25
+ ::: code-group
26
+ ```ruby [app/models/blog.rb]
27
+ class Blog < ResourceRecord
28
+ belongs_to :user
29
+ end
30
+ ```
31
+
32
+ ```ruby [app/policies/blog_policy.rb]
33
+ class BlogPolicy < Plutonium::Resource::Policy
34
+ def create?
35
+ true
36
+ end
37
+
38
+ def read?
39
+ true
40
+ end
41
+
42
+ def permitted_attributes_for_create
43
+ %i[user title content state published_at]
44
+ end
45
+
46
+ def permitted_attributes_for_read
47
+ %i[user title content state published_at]
48
+ end
49
+ end
50
+ ```
51
+
52
+ ```ruby [app/definitions/blog_definition.rb]
53
+ class BlogDefinition < Plutonium::Resource::Definition
54
+ end
55
+ ```
56
+ :::
57
+
58
+ ## Resource Definitions
59
+
60
+ Resource definitions customize how a resource behaves in your application. They define:
61
+ - Fields and their types
62
+ - Available actions
63
+ - Search and filtering capabilities
64
+ - Sorting options
65
+ - Display configurations
66
+
67
+ ### Basic Field Configuration
68
+
69
+ ::: code-group
70
+ ```ruby [Simple Fields]
71
+ class BlogDefinition < Plutonium::Resource::Definition
72
+ # Basic field definitions
73
+ field :content, as: :text
74
+
75
+ # Field with custom display options
76
+ field :published_at,
77
+ as: :datetime,
78
+ hint: "When this post should be published"
79
+ end
80
+ ```
81
+
82
+ ```ruby [Custom Displays]
83
+ class BlogDefinition < Plutonium::Resource::Definition
84
+ # Customize how fields are displayed
85
+ display :title, class: "col-span-full"
86
+ display :content do |f|
87
+ f.text_tag class: "prose dark:prose-invert"
88
+ end
89
+
90
+ # Custom column display in tables
91
+ column :state, align: :right
92
+ end
93
+ ```
94
+ :::
95
+
96
+ <!--
97
+ ### Working with Associations
98
+
99
+ Plutonium makes it easy to work with Rails associations:
100
+
101
+ ```ruby
102
+ class BlogDefinition < Plutonium::Resource::Definition
103
+ # Define belongs_to association
104
+ field :user, as: :belongs_to
105
+
106
+ # Has-many association with inline creation
107
+ field :comments do |f|
108
+ f.has_many_tag nested: true
109
+ end
110
+
111
+ # Configure nested attributes
112
+ define_nested_input :comments,
113
+ inputs: %i[content user],
114
+ limit: 3 do |input|
115
+ input.define_field_input :content,
116
+ type: :text,
117
+ hint: "Keep it constructive"
118
+ end
119
+ end
120
+ ```
121
+ -->
122
+
123
+ ### Adding Custom Actions
124
+
125
+ Beyond CRUD, you can add custom actions to your resources:
126
+
127
+ ```ruby
128
+ # app/interactions/blogs/publish.rb
129
+ module Blogs
130
+ class Publish < Plutonium::Resource::Interaction
131
+ # Define what this interaction accepts
132
+ attribute :resource, class: Blog
133
+ attribute :publish_date, :date, default: -> { Time.current }
134
+
135
+ presents label: "Publish Blog",
136
+ icon: Phlex::TablerIcons::Send,
137
+ description: "Make this blog post public"
138
+
139
+ private
140
+
141
+ def execute
142
+ if resource.update(
143
+ state: "published",
144
+ published_at: publish_date
145
+ )
146
+ succeed(resource)
147
+ .with_message("Blog post published successfully")
148
+ .with_redirect_response(resource)
149
+ else
150
+ failed(resource.errors)
151
+ end
152
+ end
153
+ end
154
+ end
155
+
156
+ # app/definitions/blog_definition.rb
157
+ class BlogDefinition < Plutonium::Resource::Definition
158
+ # Register the custom action
159
+ action :publish,
160
+ interaction: Blogs::Publish,
161
+ category: :primary
162
+ end
163
+ ```
164
+
165
+ ### Search and Filtering
166
+
167
+ Add search and filtering capabilities to your resources:
168
+
169
+ ```ruby
170
+ class BlogDefinition < Plutonium::Resource::Definition
171
+ # Enable full-text search
172
+ search do |scope, query|
173
+ scope.where("title ILIKE ? OR content ILIKE ?",
174
+ "%#{query}%", "%#{query}%")
175
+ end
176
+
177
+ # Add filters
178
+ filter :state,
179
+ with: SelectFilter,
180
+ choices: %w[draft published]
181
+
182
+ filter :published_at,
183
+ with: DateFilter,
184
+ predicate: :gteq
185
+
186
+ # Add scopes
187
+ scope :published do |scope|
188
+ where(state: "published")
189
+ end
190
+ scope :draft do |scope|
191
+ where(state: "draft")
192
+ end
193
+
194
+ # Configure sorting
195
+ sort :title
196
+ sort :published_at
197
+ end
198
+ ```
199
+
200
+ ## Resource Policies
201
+
202
+ Policies control access to your resources:
203
+
204
+ ```ruby
205
+ class BlogPolicy < Plutonium::Resource::Policy
206
+ def permitted_attributes_for_create
207
+ %i[title content state published_at user_id]
208
+ end
209
+
210
+ def permitted_associations
211
+ %i[comments]
212
+ end
213
+
214
+ def create?
215
+ # Allow logged in users to create blogs
216
+ user.present?
217
+ end
218
+
219
+ def update?
220
+ # Users can only edit their own blogs
221
+ record.user_id == user.id
222
+ end
223
+
224
+ def publish?
225
+ # Only editors can publish
226
+ user.editor? && record.draft?
227
+ end
228
+
229
+ # Scope visible records
230
+ relation_scope do |relation|
231
+ relation = super(relation)
232
+ next relation unless user.admin?
233
+
234
+ relation.with_deleted
235
+ end
236
+ end
237
+ ```
238
+
239
+ ## Best Practices
240
+
241
+ ::: tip Resource Organization
242
+ 1. Keep resource definitions focused and cohesive
243
+ 2. Use packages to organize related resources
244
+ 3. Leverage policy scopes for authorization
245
+ 4. Extract complex logic into interactions
246
+ 5. Use presenters for view-specific logic
247
+ :::
248
+
249
+ ::: warning Common Pitfalls
250
+ - Avoid putting business logic in definitions
251
+ - Don't bypass policy checks
252
+ - Remember to scope resources appropriately
253
+ - Test your interactions and policies
254
+ :::
@@ -0,0 +1,211 @@
1
+ # What is Plutonium?
2
+
3
+ Plutonium is a Rapid Application Development (RAD) toolkit that extends Rails with powerful conventions, patterns, and tools to accelerate application development while maintaining flexibility and maintainability.
4
+
5
+ It acts as a higher-level abstraction on top of Rails, providing ready-to-use solutions for common application needs while preserving Rails' elegance.
6
+
7
+ ## Core Architecture
8
+
9
+ ### Rails-Native Design
10
+
11
+ Plutonium integrates seamlessly with Rails, extending its conventions rather than replacing them:
12
+
13
+ ```ruby
14
+ # Plutonium controllers inherit from your ApplicationController
15
+ class ResourceController < ApplicationController
16
+ include Plutonium::Resource::Controller
17
+ end
18
+
19
+ # Plutonium controllers are Rails controllers
20
+ class ProductsController < ResourceController
21
+ # Enhanced with resource capabilities
22
+ def custom_action
23
+ # Regular Rails code works just fine
24
+ respond_to do |format|
25
+ format.html
26
+ format.json
27
+ end
28
+ end
29
+ end
30
+ ```
31
+
32
+ ### Resource-Oriented Architecture
33
+
34
+ Resources are the building blocks of Plutonium applications:
35
+
36
+ ```ruby
37
+ class ProductDefinition < ResourceDefinition
38
+ # Declarative field definitions
39
+ field :name, as: :string
40
+ field :description, as: :markdown
41
+ field :price_cents, as: :money
42
+
43
+ # Resource-level search
44
+ search do |scope, query|
45
+ scope.where("name LIKE ?", "%#{query}%")
46
+ end
47
+
48
+ # Business actions
49
+ action :publish, interaction: PublishProduct
50
+ action :archive, interaction: ArchiveProduct
51
+ end
52
+ ```
53
+
54
+ ### Modular by Design
55
+
56
+ Plutonium's packaging system helps organize code into focused, reusable modules:
57
+
58
+ ```ruby
59
+ # Generate different types of packages
60
+ rails generate pu:pkg:portal admin
61
+ rails generate pu:pkg:package inventory
62
+
63
+ # Packages are isolated and focused
64
+ module AdminPortal
65
+ class Engine < Rails::Engine
66
+ include Plutonium::Portal::Engine
67
+ end
68
+ end
69
+
70
+ AdminPortal::Engine.routes.draw do
71
+ register_resource ::Product
72
+ end
73
+ ```
74
+
75
+ ### Progressive Enhancement
76
+
77
+ Built on modern web technologies like Hotwire, delivering rich interactivity without sacrificing simplicity:
78
+
79
+ ```ruby
80
+ class PublishProduct < ResourceInteraction
81
+ attribute :schedule_for, :datetime
82
+ attribute :notify_users, :boolean
83
+
84
+ def execute
85
+ resource.publish!(schedule_for:)
86
+ notify_users! if notify_users
87
+
88
+ success(resource)
89
+ .with_message("Product scheduled for publishing")
90
+ .with_render_response(NotificationComponent.new)
91
+ end
92
+ end
93
+ ```
94
+
95
+ ## Use Cases
96
+
97
+ ### Business Applications
98
+
99
+ ::: details Enterprise Resource Planning (ERP)
100
+ ```ruby
101
+ class InvoiceDefinition < ResourceDefinition
102
+ # Rich field handling
103
+ field :line_items, as: :nested, limit: 20
104
+ field :attachments, as: :document, multiple: true
105
+
106
+ # Business actions
107
+ action :submit_for_approval, interaction: SubmitForApproval
108
+ action :approve, interaction: ApproveInvoice
109
+ action :reject, interaction: RejectInvoice
110
+
111
+ # Workflow states
112
+ scope :draft
113
+ scope :pending_approval
114
+ scope :approved
115
+ end
116
+ ```
117
+ :::
118
+
119
+ ::: details Multi-tenant SaaS
120
+ ```ruby
121
+ module CustomerPortal
122
+ class Engine < Rails::Engine
123
+ include Plutonium::Package::Engine
124
+ # Automatic tenant isolation
125
+ scope_to_entity Organization
126
+ end
127
+ end
128
+ ```
129
+ :::
130
+
131
+ ### Administrative Systems
132
+
133
+ ::: details Back-office Applications
134
+ ```ruby
135
+ class OrderDefinition < ResourceDefinition
136
+ # Advanced filtering
137
+ filter :status, with: SelectFilter, choices: Order.statuses
138
+ filter :created_at, with: DateRangeFilter
139
+
140
+ # Bulk actions
141
+ action :process_batch, interaction: ProcessPendingOrders
142
+ action :export_to_csv, interaction: ExportOrders
143
+
144
+ # Complex displays
145
+ display :summary do |field|
146
+ OrderSummaryComponent.new(field)
147
+ end
148
+ end
149
+ ```
150
+ :::
151
+
152
+ ::: details Content Management
153
+ ```ruby
154
+ class ArticleDefinition < ResourceDefinition
155
+ field :content, as: :markdown
156
+ field :featured_image, as: :image
157
+
158
+ # Publishing workflow
159
+ action :publish, interaction: PublishArticle
160
+ action :schedule, interaction: ScheduleArticle
161
+
162
+ # Content organization
163
+ scope :draft
164
+ scope :published
165
+ scope :scheduled
166
+ end
167
+ ```
168
+ :::
169
+
170
+ ## Key Benefits
171
+
172
+ ### Accelerated Development
173
+ - Pre-built components for common functionality
174
+ - Smart generators for boilerplate code
175
+ - Convention-based resource handling
176
+ - Integrated authentication and authorization
177
+
178
+ ### Maintainable Architecture
179
+ - Clear separation of concerns through packages
180
+ - Consistent patterns across the application
181
+ - Deep Rails integration
182
+ - Progressive enhancement
183
+
184
+ ### Enterprise Ready
185
+ - Flexible and robust access control
186
+ - Multi-tenancy support
187
+ - Extensible component system
188
+ - Mobile-friendly by default
189
+
190
+ ## Best For
191
+
192
+ ::: tip IDEAL USE CASES
193
+ - Complex business applications
194
+ - Multi-tenant SaaS platforms
195
+ - Administrative systems
196
+ - Content management systems
197
+ - Resource management systems
198
+ :::
199
+
200
+ ::: warning MIGHT NOT BE THE BEST FIT
201
+ - Simple blogs or brochure sites
202
+ - Basic CRUD applications
203
+ - Pure API-only services
204
+ :::
205
+
206
+ ## Prerequisites
207
+
208
+ - Ruby 3.2.2 or higher
209
+ - Rails 7.1 or higher
210
+ - Node.js and Yarn
211
+ - Basic understanding of Ruby on Rails
data/docs/index.md ADDED
@@ -0,0 +1,43 @@
1
+ ---
2
+ # https://vitepress.dev/reference/default-theme-home-page
3
+ layout: home
4
+
5
+ hero:
6
+ name: Plutonium RADKit
7
+ tagline: The Ultimate Rapid Application Development Toolkit (RADKit) for Rails
8
+ image:
9
+ src: /plutonium.png
10
+ alt: Plutonium
11
+ actions:
12
+ - theme: brand
13
+ text: Get started
14
+ link: /guide/getting-started/
15
+ - theme: alt
16
+ text: Learn more
17
+ link: /guide/what-is-plutonium
18
+
19
+ features:
20
+ - title: Pro-Grade CRUD UI
21
+ details: Stunning, modern interface with rich field types to build powerful admin panels in minutes
22
+
23
+ - title: Intelligent Fields
24
+ details: Zero-config field detection that matches your Rails models out of the box
25
+
26
+ - title: Seamless Authentication
27
+ details: Use your existing auth or our Rodauth integration - get setup in seconds
28
+
29
+ - title: Enterprise Authorization
30
+ details: Industrial-strength access control powered by Action Policy's proven framework
31
+
32
+ - title: Built-in Multitenancy
33
+ details: Row-level multitenancy that just works - perfect for SaaS and enterprise apps
34
+
35
+ - title: Advanced Nested Resources
36
+ details: Complex resource relationships made simple with zero extra configuration
37
+
38
+ - title: Custom Actions
39
+ details: Extend your admin panel with incredibly simple custom actions and workflows
40
+
41
+ - title: Complete Builder Control
42
+ details: Total flexibility to customize every aspect of your admin UI with elegant builder APIs
43
+ ---
@@ -0,0 +1,85 @@
1
+ # Markdown Extension Examples
2
+
3
+ This page demonstrates some of the built-in markdown extensions provided by VitePress.
4
+
5
+ ## Syntax Highlighting
6
+
7
+ VitePress provides Syntax Highlighting powered by [Shiki](https://github.com/shikijs/shiki), with additional features like line-highlighting:
8
+
9
+ **Input**
10
+
11
+ ````md
12
+ ```js{4}
13
+ export default {
14
+ data () {
15
+ return {
16
+ msg: 'Highlighted!'
17
+ }
18
+ }
19
+ }
20
+ ```
21
+ ````
22
+
23
+ **Output**
24
+
25
+ ```js{4}
26
+ export default {
27
+ data () {
28
+ return {
29
+ msg: 'Highlighted!'
30
+ }
31
+ }
32
+ }
33
+ ```
34
+
35
+ ## Custom Containers
36
+
37
+ **Input**
38
+
39
+ ```md
40
+ ::: info
41
+ This is an info box.
42
+ :::
43
+
44
+ ::: tip
45
+ This is a tip.
46
+ :::
47
+
48
+ ::: warning
49
+ This is a warning.
50
+ :::
51
+
52
+ ::: danger
53
+ This is a dangerous warning.
54
+ :::
55
+
56
+ ::: details
57
+ This is a details block.
58
+ :::
59
+ ```
60
+
61
+ **Output**
62
+
63
+ ::: info
64
+ This is an info box.
65
+ :::
66
+
67
+ ::: tip
68
+ This is a tip.
69
+ :::
70
+
71
+ ::: warning
72
+ This is a warning.
73
+ :::
74
+
75
+ ::: danger
76
+ This is a dangerous warning.
77
+ :::
78
+
79
+ ::: details
80
+ This is a details block.
81
+ :::
82
+
83
+ ## More
84
+
85
+ Check out the documentation for the [full list of markdown extensions](https://vitepress.dev/guide/markdown).
Binary file
Binary file
Binary file
Binary file
Binary file
@@ -0,0 +1 @@
1
+ {"name":"","short_name":"","icons":[{"src":"/android-chrome-192x192.png","sizes":"192x192","type":"image/png"},{"src":"/android-chrome-512x512.png","sizes":"512x512","type":"image/png"}],"theme_color":"#ffffff","background_color":"#ffffff","display":"standalone"}
@@ -0,0 +1,21 @@
1
+ after_bundle do
2
+ # We just installed Rails, let's create a commit
3
+ git add: "."
4
+ git commit: %( -m 'initial commit' )
5
+
6
+ # Run the base install
7
+ rails_command "app:template LOCATION=https://radioactive-labs.github.io/plutonium-core/templates/base.rb"
8
+
9
+ # Add development tools
10
+ generate "pu:gem:dotenv"
11
+ git add: "."
12
+ git commit: %( -m 'add dotenv' )
13
+
14
+ generate "pu:gem:annotate"
15
+ git add: "."
16
+ git commit: %( -m 'add annotate' )
17
+
18
+ generate "pu:core:assets"
19
+ git add: "."
20
+ git commit: %( -m 'integrate assets' )
21
+ end
@@ -22,12 +22,11 @@ module Pu
22
22
  private
23
23
 
24
24
  def copy_tailwind_config
25
- copy_file "tailwind.config.js"
25
+ copy_file "tailwind.config.js", force: true
26
26
  end
27
27
 
28
28
  def install_dependencies
29
- `yarn add @radioactive-labs/plutonium`
30
- `yarn add flowbite @tailwindcss/forms`
29
+ run "npm install @radioactive-labs/plutonium flowbite @tailwindcss/forms"
31
30
  end
32
31
 
33
32
  def configure_application
@@ -9,12 +9,12 @@ module.exports = {
9
9
  ].concat(plutoniumTailwindConfig.plugins.map((plugin) => require(plugin))),
10
10
  theme: plutoniumTailwindConfig.theme,
11
11
  content: [
12
+ `${__dirname}/app/**/*.rb`,
12
13
  `${__dirname}/app/views/**/*.html.erb`,
13
14
  `${__dirname}/app/helpers/**/*.rb`,
14
15
  `${__dirname}/app/assets/stylesheets/**/*.css`,
15
16
  `${__dirname}/app/javascript/**/*.js`,
16
- `${__dirname}/app/plutonium/**/*.rb`,
17
- `${__dirname}/packages/**/app/plutonium/**/*.rb`,
17
+ `${__dirname}/packages/**/app/**/*.rb`,
18
18
  `${__dirname}/packages/**/app/views/**/*.html.erb`,
19
19
  ].concat(plutoniumTailwindConfig.content),
20
20
  }
@@ -15,6 +15,7 @@ module Pu
15
15
  setup_packages
16
16
  setup_app
17
17
  eject_views
18
+ setup_active_record
18
19
  rescue => e
19
20
  exception "#{self.class} failed:", e
20
21
  end
@@ -25,7 +26,6 @@ module Pu
25
26
  copy_file "config/packages.rb"
26
27
  create_file "packages/.keep"
27
28
  insert_into_file "config/application.rb", "\nrequire_relative \"packages\"\n", after: /Bundler\.require.*\n/
28
- # insert_into_file "config/application.rb", indent("Plutonium.configure_rails config\n\n", 4), after: /.*< Rails::Application\n/
29
29
  end
30
30
 
31
31
  def setup_app
@@ -38,6 +38,14 @@ module Pu
38
38
  force: options[:force],
39
39
  skip: options[:skip]
40
40
  end
41
+
42
+ def setup_active_record
43
+ inject_into_class(
44
+ "app/models/application_record.rb",
45
+ "ApplicationRecord",
46
+ " include Plutonium::Resource::Record\n"
47
+ )
48
+ end
41
49
  end
42
50
  end
43
51
  end
@@ -3,6 +3,5 @@
3
3
  Plutonium.configure do |config|
4
4
  config.load_defaults 1.0
5
5
 
6
- # config.assets.logo = "logo.png"
7
6
  # Configure plutonium above.
8
7
  end