plutonium 0.33.1 → 0.34.0

data/docs/guide/tutorial/04-creating-a-portal.md

@@ -1,101 +0,0 @@
-# 4. Creating a Portal
-
-We have our `Blogging` feature package with `Post` and `Comment` resources, but no user interface to manage them. Let's create a **Portal** to serve as a web interface for our blog.
-
-## What are Portal Packages?
-
-While Feature Packages hold business logic, **Portal Packages** provide the web interface. They are also Rails Engines, but they are responsible for things like:
-
-- Dashboards and layouts.
-- Routing requests to the correct resources.
-- Handling user authentication for the interface.
-
-We'll create a `Dashboard` portal for managing our blog.
-
-## Generate the Portal
-
-Plutonium has a generator for portals. In your terminal, run:
-
-```bash
-rails generate pu:pkg:portal dashboard
-```
-
-The generator will ask which authentication account to use. We already set up the `user` account with Rodauth, so **select `user`**.
-
-This creates a new package at `packages/dashboard_portal/` and wires it up for authentication.
-
-## Connect Resources to the Portal
-
-Now we need to tell our new `Dashboard` portal which resources it should manage. We can use the `pu:res:conn` (connect) generator for this.
-
-Run the connect generator:
-```bash
-rails generate pu:res:conn
-```
-
-It will ask you a series of questions:
-1.  **Select source feature**: Choose **`blogging`**.
-2.  **Select resources**: Use the spacebar to select both **`Blogging::Post`** and **`Blogging::Comment`**, then press Enter.
-3.  **Select destination portal**: Choose **`dashboard_portal`**.
-
-This command does the magic of connecting your feature logic to your UI. It updates the portal's routes file (`packages/dashboard_portal/config/routes.rb`) to register the resources:
-
-```ruby
-# packages/dashboard_portal/config/routes.rb
-DashboardPortal::Engine.routes.draw do
-  root to: "dashboard#index"
-
-  register_resource Blogging::Post
-  register_resource Blogging::Comment
-end
-```
-
-## Configure Application Routes
-
-There's one last step. We need to tell our main Rails application how to handle routing for authentication and the new dashboard.
-
-1.  **Update Rodauth Redirects**: We want users to be sent to the dashboard after they log in or sign up.
-
-    ```ruby [app/rodauth/user_rodauth_plugin.rb]
-    # ==> Redirects
-
-    # Redirect to home after login.
-    create_account_redirect "/" # [!code --]
-    create_account_redirect "/dashboard" # [!code ++]
-
-    # Redirect to home after login.
-    login_redirect "/" # [!code --]
-    login_redirect "/dashboard" # [!code ++]
-
-    # Redirect to home page after logout.
-    logout_redirect "/" # [!code --]
-    logout_redirect "/dashboard" # [!code ++]
-    ```
-
-2.  **Update Root Route**: We'll make the dashboard the root of our application.
-
-    ```ruby [config/routes.rb]
-    Rails.application.routes.draw do
-      # ...
-      # Defines the root path route ("/")
-      # root "posts#index" # [!code --]
-      root to: redirect("/dashboard") # [!code ++]
-    end
-    ```
-
-## See it in Action!
-
-Let's check our progress. Start your Rails server (`bin/dev`) and navigate to [http://localhost:3000](http://localhost:3000).
-
-You will be redirected to `/dashboard` and should see the login page.
-
-- **Sign up** for a new account.
-- After signing up, you'll be redirected to the dashboard. It will be empty for now, but this confirms the portal and authentication are working!
-
-![Plutonium Empty Dashboard](/tutorial/plutonium-posts-dashboard.png)
-
-## Next Steps
-
-We now have a functional dashboard! It's not very useful yet, though.
-
-In the next chapter, we will customize the user interface to display our posts and comments, and add navigation to make them accessible.

data/docs/guide/tutorial/05-customizing-the-ui.md

@@ -1,128 +0,0 @@
-# 5. Customizing the UI
-
-Our dashboard is functional, but it's not very user-friendly. In Plutonium, customizing the UI is a two-step process that respects the separation of concerns:
-
-1.  **Policy (`app/policies`)**: The policy file controls **what** a user is authorized to see or edit. This is a security layer.
-2.  **Definition (`app/definitions`)**: The definition file controls **how** those permitted fields are displayed and formatted. This is a presentation layer.
-
-Let's customize our `Post` resource by following this two-step process for the table, detail page, and form.
-
-## Customizing the Posts Table (Index View)
-
-First, we'll define **what** columns should appear in the posts table. This is an authorization concern, so we'll use the policy file.
-
-Open the post policy: `packages/blogging/app/policies/blogging/post_policy.rb`
-
-```ruby
-# packages/blogging/app/policies/blogging/post_policy.rb
-class Blogging::PostPolicy < Blogging::ResourcePolicy
-  # ... (other methods)
-
-  # 1. Define WHAT columns are visible in the table.
-  def permitted_attributes_for_index
-    [:user, :title, :published_at, :created_at]
-  end
-end
-```
-
-Next, we'll configure **how** these columns are displayed in the definition file.
-
-Open the post definition: `packages/blogging/app/definitions/blogging/post_definition.rb`
-
-```ruby
-# packages/blogging/app/definitions/blogging/post_definition.rb
-class Blogging::PostDefinition < Blogging::ResourceDefinition
-  # 2. Define HOW the permitted columns are rendered.
-  column :published_at, as: :datetime
-  column :created_at, as: :datetime
-end
-```
-
-The table now only shows the permitted columns, formatted as we specified.
-
-![Plutonium Posts Dashboard (Customized)](/tutorial/plutonium-posts-dashboard-customized.png)
-
-## Customizing the Post Detail Page (Show View)
-
-The same two-step process applies to the detail page.
-
-1.  **Policy**: Define what fields are visible with `permitted_attributes_for_show`.
-2.  **Definition**: Define how they are rendered with `display`.
-
-Let's define the fields in the policy. For this view, we want to show the `:content`.
-
-```ruby
-# packages/blogging/app/policies/blogging/post_policy.rb
-class Blogging::PostPolicy < Blogging::ResourcePolicy
-  # ...
-
-  def permitted_attributes_for_index
-    [:user, :title, :published_at, :created_at]
-  end
-
-  # 1. Define WHAT fields are visible on the show page.
-  def permitted_attributes_for_show
-    [:user, :title, :content, :published_at, :created_at]
-  end
-end
-```
-
-Now, let's configure the layout in the definition. We'll make each field take up the full width of the view.
-
-```ruby
-# packages/blogging/app/definitions/blogging/post_definition.rb
-class Blogging::PostDefinition < Blogging::ResourceDefinition
-  display :user, wrapper: { class: "col-span-full" }
-  display :title, wrapper: { class: "col-span-full" }
-  display :content, wrapper: { class: "col-span-full" }
-  display :published_at, wrapper: { class: "col-span-full" }
-  display :created_at, wrapper: { class: "col-span-full" }
-end
-```
-
-![Plutonium Posts Detail (Customized)](/tutorial/plutonium-posts-detail-customized.png)
-
-## Customizing the Post Form
-
-Finally, we'll customize the `new` and `edit` forms.
-
-1.  **Policy**: Use `permitted_attributes_for_create` and `_for_update` to control which fields can be submitted.
-2.  **Definition**: Use the `input` helper to control how the form inputs are rendered.
-
-First, the policy. We don't want the user to be able to set the `published_at` date directly in the form.
-
-```ruby
-# packages/blogging/app/policies/blogging/post_policy.rb
-class Blogging::PostPolicy < Blogging::ResourcePolicy
-  # ...
-
-  # 1. Define WHAT fields can be submitted in the form.
-  def permitted_attributes_for_create
-    [:user_id, :title, :content]
-  end
-
-  def permitted_attributes_for_update
-    permitted_attributes_for_create
-  end
-end
-```
-
-Now, the definition. We'll use the `input` helper to specify that `:content` should use a rich text editor.
-
-```ruby
-# packages/blogging/app/definitions/blogging/post_definition.rb
-class Blogging::PostDefinition < Blogging::ResourceDefinition
-  # ... (display helpers from above)
-
-  # 2. Define HOW the form inputs are rendered.
-  input :content, as: :rich_text # Use a rich text editor
-end
-```
-
-By separating what is permitted from how it is rendered, Plutonium gives you both security and flexibility.
-
-## Next Steps
-
-Our UI is now much more polished. We've used the **Policy** and **Definition** files together to customize our `Post` resource.
-
-In the next chapter, we'll add custom business logic by creating an **Action** to publish a draft post.

data/docs/guide/tutorial/06-adding-custom-actions.md

@@ -1,101 +0,0 @@
-# 6. Adding Custom Actions
-
-Our application now handles the basics of creating, reading, updating, and deleting posts and comments. But what about business logic that isn't simple CRUD? For this, Plutonium has **Actions**.
-
-An Action is a piece of business logic you can execute on a resource. We'll create a "Publish" action for our posts.
-
-Create a new file for our "interaction" at:
-`packages/blogging/app/interactions/blogging/post_interactions/publish.rb`
-
-## Implement the Interaction
-
-The "Interaction" is where the business logic for an action lives. Open the newly created file and let's implement the logic to publish a post.
-
-We want the action to set the `published_at` timestamp on the post.
-
-```ruby
-# packages/blogging/app/interactions/blogging/post_interactions/publish.rb
-module Blogging
-  module PostInteractions
-    class Publish < Plutonium::Resource::Interaction
-      # Define the attributes this interaction accepts
-      attribute :resource, class: "Blogging::Post"
-
-      # Define how this action is presented in the UI
-      presents label: "Publish Post",
-               description: "Make this post available for the public to see."
-
-      private
-
-      # The core business logic
-      def execute
-        if resource.update(published_at: Time.current )
-          succeed(resource)
-            .with_message("Post was successfully published.")
-            .with_redirect_response(resource)
-        else
-          failed(resource.errors)
-        end
-      end
-    end
-  end
-end
-```
-
-This class defines what the action needs (`resource`, `published_at`), how it looks (`presents`), and what it does (`execute`).
-
-## Configure the Action
-
-Now that we've defined the logic, we need to add the action to our `Post` resource and configure its visibility. We'll do this in the post's **definition** file.
-
-`packages/blogging/app/definitions/blogging/post_definition.rb`
-
-Add the `action` configuration:
-
-```ruby
-# packages/blogging/app/definitions/blogging/post_definition.rb
-class Blogging::PostDefinition < Blogging::ResourceDefinition
-  # ... (display helpers from the previous chapter)
-
-  action :publish,
-    interaction: "Blogging::PostInteractions::Publish"
-end
-```
-
-## Control Visibility with a Policy
-
-Plutonium actions are secure by default. If an action doesn't have a corresponding policy method allowing it, it won't be displayed.
-
-Let's define the logic for our `publish` action. We only want to show the "Publish" button if the post hasn't been published yet.
-
-Open the post policy file:
-`packages/blogging/app/policies/blogging/post_policy.rb`
-
-Add the `publish?` method:
-
-```ruby
-# packages/blogging/app/policies/blogging/post_policy.rb
-class Blogging::PostPolicy < Blogging::ResourcePolicy
-  # ... (other methods from previous chapters)
-
-  def publish?
-    # Only allow publishing if the user can update the post
-    # and the post has not been published yet.
-    update? && record.published_at.nil?
-  end
-end
-```
-
-This policy does two things:
-1. It ensures the user has permission to `update?` the post.
-2. It checks that `published_at` is `nil`.
-
-Now, go to the show page for a post you created. You should see the "Publish" button. Click it, and the `published_at` field will be set. Because `record.published_at.nil?` is now false, the policy will prevent the action from being shown again. The button disappears!
-
-![Plutonium Posts Publish Action](/tutorial/plutonium-publish-post.png)
-
-## Next Steps
-
-We've successfully added custom business logic to our application. Actions are a powerful way to build complex, maintainable features.
-
-In the final chapter of this tutorial, we'll tighten up security by implementing proper authorization rules.

data/docs/guide/tutorial/07-implementing-authorization.md

@@ -1,90 +0,0 @@
-# 7. Implementing Authorization
-
-Our blog is now fully functional, but it's not very secure. Any user can edit or delete any other user's posts. Let's fix this by implementing proper authorization rules using Plutonium's **Policy** system.
-
-## Understanding Policies
-
-For every resource, there is a corresponding Policy class that controls access. The policy methods (like `update?` or `destroy?`) return `true` or `false` to grant or deny permission.
-
-## Securing Post Actions
-
-Let's start by restricting the `update` and `publish` actions for posts. Open the post policy file:
-
-`packages/blogging/app/policies/blogging/post_policy.rb`
-
-Now, let's modify the policy to check if the current user (`user`) is the owner of the post (`record`).
-
-```ruby
-# packages/blogging/app/policies/blogging/post_policy.rb
-class Blogging::PostPolicy < Blogging::ResourcePolicy
-  # Users can only update their own posts
-  def update?
-    record.user_id == user.id
-  end
-
-  # Only the owner can publish their post
-  def publish?
-    update? # Inherits from update?
-  end
-end
-```
-By default, `destroy?` also inherits from `update?`, so this one change secures all write operations.
-
-## Securing Comment Actions
-
-We should apply the same logic to comments. Open the comment policy:
-
-`packages/blogging/app/policies/blogging/comment_policy.rb`
-
-And add the same ownership check:
-
-```ruby
-# packages/blogging/app/policies/blogging/comment_policy.rb
-class Blogging::CommentPolicy < Blogging::ResourcePolicy
-  def update?
-    record.user_id == user.id
-  end
-end
-```
-
-## Scoping Visible Data
-
-We've secured the actions, but there's one more problem: every user can see every post in the index view. We should scope the list of posts so that users only see their own.
-
-This is done with the `relation_scope` in the post policy file. This scope is applied to all queries for the `Post` resource.
-
-`packages/blogging/app/policies/blogging/post_policy.rb`
-
-```ruby
-# packages/blogging/app/policies/blogging/post_policy.rb
-class Blogging::PostPolicy < Blogging::ResourcePolicy
-  # ... (update? and publish? methods)
-
-  # Scope all queries to only include the current user's posts
-  relation_scope do |scope|
-    scope.where(user: user)
-  end
-end
-```
-Now, the posts index page will only show posts created by the currently logged-in user. This is a critical feature for multi-tenant applications.
-
-## Tutorial Complete!
-
-Congratulations! You have built a complete, secure, and modular blog application with Plutonium.
-
-You've learned how to:
-- Set up a Plutonium project.
-- Organize features into **Packages**.
-- Define and scaffold **Resources**.
-- Build a web interface with **Portals**.
-- Customize the UI.
-- Add custom business logic with **Actions**.
-- Secure your application with **Policies**.
-
-### Where to Go Next?
-
-You now have a strong foundation to build your own applications. To learn more about specific topics, check out our **Deep Dive Guides**:
-
-- **[Resources](./../deep-dive/resources.md)**: An in-depth look at fields, associations, filters, and more.
-- **[Authorization](./../deep-dive/authorization.md)**: A detailed guide to policies, scopes, and entity-based authorization.
-- ... more guides coming soon!

data/docs/markdown-examples.md

@@ -1,85 +0,0 @@
-# Markdown Extension Examples
-
-This page demonstrates some of the built-in markdown extensions provided by VitePress.
-
-## Syntax Highlighting
-
-VitePress provides Syntax Highlighting powered by [Shiki](https://github.com/shikijs/shiki), with additional features like line-highlighting:
-
-**Input**
-
-````md
-```js{4}
-export default {
-  data () {
-    return {
-      msg: 'Highlighted!'
-    }
-  }
-}
-```
-````
-
-**Output**
-
-```js{4}
-export default {
-  data () {
-    return {
-      msg: 'Highlighted!'
-    }
-  }
-}
-```
-
-## Custom Containers
-
-**Input**
-
-```md
-::: info
-This is an info box.
-:::
-
-::: tip
-This is a tip.
-:::
-
-::: warning
-This is a warning.
-:::
-
-::: danger
-This is a dangerous warning.
-:::
-
-::: details
-This is a details block.
-:::
-```
-
-**Output**
-
-::: info
-This is an info box.
-:::
-
-::: tip
-This is a tip.
-:::
-
-::: warning
-This is a warning.
-:::
-
-::: danger
-This is a dangerous warning.
-:::
-
-::: details
-This is a details block.
-:::
-
-## More
-
-Check out the documentation for the [full list of markdown extensions](https://vitepress.dev/guide/markdown).