organizations 0.4.1 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5a2f3a64510fcf3f08245894e49fbdd1a2aae8e76b9b9fb17fa2a6baa212c3e9
-  data.tar.gz: 593fdc944621beb95f6bb318ade8ae88e4933a81f25bd273253704ab9f491f05
+  metadata.gz: 916bef6e3c027111a6da0cfa08cf015f2d872de614d55ab8978ce41e2a8ab8aa
+  data.tar.gz: 6d0fb70f4292c7a7635d16acde00f7b88cdbc9fdcc8d4268d76b65010bf16667
 SHA512:
-  metadata.gz: 3c5327208fd86db81f8255bf95405736abc01e374e72a190041f31eb4ced7cff63bf2cb7b040d3a4dfc32fcdde7d11282ad6949c70a282eaed1454f318dc9908
-  data.tar.gz: 7537c69f044a08a8e8422549b4b9272768c412ef3c13a97600808bb8b1a5d1102479c7d9c5c5d61e062ecec84be92132a687405f751033fdfc58f29fc2ca0227
+  metadata.gz: 78deb6016d5e62f432c1949ee9b8f700ce370e75a682451ace35a6923eb208e8f83800312cb525631fc1ee150a832f2748a67ab05b7f714873ca4b09b4e67adc
+  data.tar.gz: 529a7721cf5eef70b856a6b6e357e6d8881caf5b9108f31651cc2be7d83ea4258bde159b9a39d787ea78d71ed2b80d61939e1e5576c575df9416719729582c2f

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+## [0.4.2] - 2026-03-19
+
+- Added `should_create_personal_organization?` predicate as extension seam for conditional personal org creation
+- DSL `create_personal_organization` setting now accepts procs for dynamic evaluation
+- Added `DELETE /memberships/leave` route for users to leave organizations
+- Updated owner deletion guard message to clarify transfer/delete solution
+- Documentation: added "Pattern 4: Hybrid Onboarding" to README
+
 ## [0.4.1] - 2026-03-17
 
 - Fixed `memberships_count` counter cache writes on `Organizations::Membership.create!`

data/README.md

@@ -9,7 +9,7 @@
 
 **🎮 [Try the live demo →](https://organizations.rameerez.com)**
 
-[TODO: invitation / member management gif]
+https://github.com/user-attachments/assets/2eddafe2-025b-4670-af9f-e0d5480508c5
 
 It's everything you need to turn a `User`-based app into a multi-tenant, `Organization`-based B2B SaaS (users belong in organizations, and organizations share resources and billing, etc.)
 
@@ -74,13 +74,13 @@ That's the simplest setup. You can also configure per-model options:
 class User < ApplicationRecord
   has_organizations do
     max_organizations 5         # Limit how many orgs a user can own (nil = unlimited)
-    create_personal_org true    # Auto-create org on signup (default: false)
+    create_personal_org true    # Auto-create org on signup (default: false). Can also be a proc.
     require_organization true   # Require users to have at least one org (default: false)
   end
 end
 ```
 
-> **Note:** By default, users can exist without any organization (invite-to-join flow). Set `create_personal_org true` if you want to auto-create a personal organization when users sign up.
+> **Note:** By default, users can exist without any organization (invite-to-join flow). Set `create_personal_org true` if you want to auto-create a personal organization when users sign up. For conditional creation, use a proc: `create_personal_org ->(user) { ... }` or override `should_create_personal_organization?` on your User model (see Pattern 4: Hybrid Onboarding).
 
 Mount the engine in your routes:
 
@@ -108,6 +108,8 @@ org = current_user.create_organization!("Acme Corp")
 
 ### Invite teammates
 
+<img src="docs/organizations-team-members.webp" width="500" />
+
 ```ruby
 current_user.send_organization_invite_to!("teammate@example.com")
 # Sends invitation email: "John invited you to join Acme Corp"
@@ -122,6 +124,8 @@ current_user.send_organization_invite_to!("teammate@example.com", organization:
 
 ### Check roles and permissions
 
+<img src="docs/organizations-member-permissions.webp" width="500" />
+
 ```ruby
 # Quick role checks (in current organization)
 current_user.is_organization_owner?   # => true/false
@@ -141,6 +145,8 @@ current_user.is_member_of?(@org)
 
 ### Switch between organizations
 
+<img src="docs/organizations-switcher.webp" width="400" />
+
 ```ruby
 # User belongs to multiple organizations? No problem.
 current_user.organizations        # => [acme, startup_co, personal]
@@ -652,6 +658,8 @@ org.send_invite_to!("teammate@example.com", invited_by: current_user)
 
 The gem handles **both existing users and new signups** with a single invitation link:
 
+<img src="docs/organizations-invitation-accept-create-account.webp" width="500" />
+
 **For existing users:**
 1. Invitation created → Email sent with unique link
 2. User clicks link → Sees invitation details (org name, inviter, role)
@@ -888,6 +896,165 @@ Organizations.configure do |config|
 end
 ```
 
+## User Onboarding Patterns
+
+The `always_create_personal_organization_for_each_user` setting controls how new users get their first organization. This is one of the most important decisions when integrating the gem.
+
+### Pattern 1: Instant Access (auto-create)
+
+**Think:** Notion, Slack, Trello — "Sign up and start using it in 10 seconds"
+
+```ruby
+config.always_create_personal_organization_for_each_user = true
+config.default_organization_name = "My Workspace"
+```
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  User signs up  →  "My Workspace" created  →  Dashboard 🎉  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+Users land in the app immediately. Zero friction. They can invite teammates later.
+
+```ruby
+# config/initializers/organizations.rb
+Organizations.configure do |config|
+  config.always_create_personal_organization_for_each_user = true
+  config.default_organization_name = "My Workspace"
+  # Or personalize it:
+  # config.default_organization_name = ->(user) { "#{user.email.split('@').first}'s Workspace" }
+end
+```
+
+Best for: productivity tools, note apps, personal SaaS, anything where "just let me in" matters.
+
+### Pattern 2: Guided Onboarding (manual create)
+
+**Think:** Stripe, HubSpot, Salesforce — "Tell us about your company first"
+
+```ruby
+config.always_create_personal_organization_for_each_user = false
+config.redirect_path_when_no_organization = "/onboarding/create_organization"
+```
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│  User signs up  →  Onboarding wizard  →  "Create your company"  →  App  │
+│                    (collect company name, billing email, etc.)           │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+You control the experience. Collect whatever info you need before they enter.
+
+```ruby
+# config/initializers/organizations.rb
+Organizations.configure do |config|
+  config.always_create_personal_organization_for_each_user = false
+  config.redirect_path_when_no_organization = "/onboarding/create_organization"
+  config.no_organization_notice = "Let's set up your company first."
+  config.additional_organization_params = [:billing_email, :company_size, :industry]
+end
+```
+
+```ruby
+# app/controllers/onboarding_controller.rb
+def create_organization
+  @organization = current_user.create_organization!(
+    name: params[:company_name],
+    billing_email: params[:billing_email]
+  )
+  redirect_to dashboard_path
+end
+```
+
+Best for: B2B SaaS, enterprise tools, apps that need company details for billing/compliance.
+
+### Pattern 3: Invitation-Only
+
+**Think:** Internal company tools, private beta, enterprise deployments
+
+```ruby
+config.always_create_personal_organization_for_each_user = false
+config.redirect_path_when_no_organization = "/waiting_room"
+```
+
+```
+┌───────────────────────────────────────────────────────────────────────┐
+│  User signs up  →  "Waiting for invitation" page  →  (nothing yet)    │
+│                                                                       │
+│  Admin invites user  →  User accepts  →  Joins org  →  Dashboard 🎉   │
+└───────────────────────────────────────────────────────────────────────┘
+```
+
+Users can't do anything until an admin invites them. Full control over who gets in.
+
+Best for: internal tools, private beta programs, enterprise B2B where orgs are pre-provisioned.
+
+### Pattern 4: Hybrid Onboarding
+
+**Think:** Best of both worlds — instant access for direct signups, no clutter for invited users
+
+Direct signups get a personal workspace immediately. Invited users skip the personal workspace and join the organization that invited them directly. This avoids creating unnecessary "My Workspace" organizations for users who are joining an existing team.
+
+```
+┌──────────────────────────────────────────────────────────────────────────────┐
+│  Direct signup  →  "My Workspace" auto-created  →  Dashboard 🎉              │
+│                                                                              │
+│  Invited signup  →  No personal org  →  Joins invited org  →  Dashboard 🎉   │
+└──────────────────────────────────────────────────────────────────────────────┘
+```
+
+Implementation requires overriding the `should_create_personal_organization?` method on your User model:
+
+```ruby
+# app/models/user.rb
+class User < ApplicationRecord
+  has_organizations
+
+  # Skip personal org creation for users signing up via invitation
+  attr_accessor :skip_personal_organization
+
+  def should_create_personal_organization?
+    return false if skip_personal_organization
+    super
+  end
+end
+```
+
+Then set the flag before the user is persisted. With Devise, override `build_resource`:
+
+```ruby
+# app/controllers/users/registrations_controller.rb
+class Users::RegistrationsController < Devise::RegistrationsController
+  protected
+
+  def build_resource(hash = {})
+    super
+    # Skip personal org for users signing up via invitation
+    resource.skip_personal_organization = true if pending_organization_invitation?
+  end
+end
+```
+
+The `should_create_personal_organization?` method is the official extension seam. It evaluates:
+1. Your method override (if defined)
+2. The `create_personal_org` setting (boolean or proc)
+3. The global `always_create_personal_organization_for_each_user` config
+
+You can also use a proc for the setting itself:
+
+```ruby
+# In has_organizations block
+has_organizations do
+  create_personal_org ->(user) { !user.skip_personal_organization }
+end
+```
+
+Best for: SaaS products that want instant onboarding for individual users but clean team onboarding for invited members.
+
+---
+
 ## Configuration
 
 Full configuration options:

data/app/controllers/organizations/memberships_controller.rb

@@ -79,6 +79,31 @@ module Organizations
       end
     end
 
+    # DELETE /memberships/leave
+    # Leave the current organization (current user removes themselves)
+    # Note: No permission guard needed — users can only leave themselves, and
+    # require_organization! ensures valid org context. Domain rules (can't leave
+    # as last owner, etc.) are enforced by leave_organization!.
+    def leave
+      org_name = current_organization.name
+
+      begin
+        current_user.leave_organization!(current_organization)
+
+        respond_to do |format|
+          format.html { redirect_to organizations_path, notice: "You have left #{org_name}." }
+          format.json { head :no_content }
+        end
+      rescue Models::Concerns::HasOrganizations::CannotLeaveLastOrganization,
+             Models::Concerns::HasOrganizations::CannotLeaveAsLastOwner,
+             Error => e
+        respond_to do |format|
+          format.html { redirect_back fallback_location: organizations_path, alert: e.message }
+          format.json { render json: { error: e.message }, status: :unprocessable_entity }
+        end
+      end
+    end
+
     # POST /memberships/:id/transfer_ownership
     # Transfer organization ownership to another member
     def transfer_ownership

data/config/routes.rb

@@ -15,6 +15,9 @@ Organizations::Engine.routes.draw do
     member do
       post :transfer_ownership
     end
+    collection do
+      delete :leave
+    end
   end
 
   # Invitation management (scoped to current_organization)

data/context7.json

@@ -0,0 +1,4 @@
+{
+  "url": "https://context7.com/rameerez/organizations",
+  "public_key": "pk_HibNJE5rTFvy1txHHXUot"
+}

data/lib/generators/organizations/install/templates/initializer.rb

@@ -6,11 +6,33 @@ Organizations.configure do |config|
   # ============================================================================
 
   # Automatically create a personal organization when a user signs up.
-  # The organization will be named after the user (e.g., "John's Organization").
+  # The organization will be named using default_organization_name (below).
   # Set to true if you want every user to have their own organization on signup.
   # Default: false (invite-to-join flow)
   # config.always_create_personal_organization_for_each_user = false
 
+  # NOTE: This is a coarse, global default. For conditional creation (e.g., skip
+  # personal org for invited signups), override should_create_personal_organization?
+  # on your User model instead:
+  #
+  #   class User < ApplicationRecord
+  #     has_organizations
+  #     attr_accessor :skip_personal_organization
+  #
+  #     def should_create_personal_organization?
+  #       return false if skip_personal_organization
+  #       super
+  #     end
+  #   end
+  #
+  # See "Pattern 4: Hybrid Onboarding" in the README for the full pattern.
+
+  # Name for auto-created organizations.
+  # Can be a string or a proc that receives the user.
+  # Default: "Personal"
+  # config.default_organization_name = "My Workspace"
+  # config.default_organization_name = ->(user) { "#{user.name}'s Workspace" }
+
   # ============================================================================
   # ORGANIZATION REQUIREMENTS
   # ============================================================================

data/lib/organizations/configuration.rb

@@ -33,10 +33,41 @@ module Organizations
     attr_accessor :authenticate_user_method
 
     # === Auto-creation ===
-    # Create personal organization on user signup
+    #
+    # Create personal organization automatically on user signup.
+    #
+    # This setting controls the user's first-time experience:
+    #
+    # ┌─────────────────────────────────────────────────────────────────────────┐
+    # │  true  → "Instant access" pattern                                       │
+    # │                                                                         │
+    # │  User signs up → auto-created workspace → lands in app immediately      │
+    # │                                                                         │
+    # │  Think: Notion, Slack, Trello                                           │
+    # │  "Sign up and start using it in seconds"                                │
+    # │                                                                         │
+    # │  Best for: productivity tools, note apps, simple SaaS                   │
+    # └─────────────────────────────────────────────────────────────────────────┘
+    #
+    # ┌─────────────────────────────────────────────────────────────────────────┐
+    # │  false → "Guided onboarding" pattern                                    │
+    # │                                                                         │
+    # │  User signs up → onboarding wizard → enters company info → dashboard    │
+    # │                                                                         │
+    # │  Think: Stripe, HubSpot, enterprise B2B tools                           │
+    # │  "Tell us about your company before you start"                          │
+    # │                                                                         │
+    # │  Best for: B2B SaaS needing company details, billing info, etc.         │
+    # └─────────────────────────────────────────────────────────────────────────┘
+    #
+    # Related settings:
+    #   - default_organization_name: Name for auto-created orgs (only when true)
+    #   - redirect_path_when_no_organization: Where to send users without an org
+    #   - always_require_users_to_belong_to_one_organization: Prevent leaving last org
+    #
     attr_accessor :always_create_personal_organization_for_each_user
 
-    # Name for auto-created organizations
+    # Name for auto-created organizations (only used when always_create_personal_organization_for_each_user = true)
     # Can be a String or a Proc/Lambda: ->(user) { "#{user.name}'s Workspace" }
     attr_accessor :default_organization_name
 

data/lib/organizations/models/concerns/has_organizations.rb

@@ -37,7 +37,8 @@ module Organizations
           # Enable organization support on this model
           # @param options [Hash] Configuration options
           # @option options [Integer, nil] :max_organizations Maximum orgs user can own
-          # @option options [Boolean] :create_personal_org Create personal org on signup
+          # @option options [Boolean, Proc] :create_personal_org Create personal org on signup.
+          #   Can be a boolean or a proc that receives the user instance for conditional creation.
           # @option options [Boolean] :require_organization Require user to have an org
           # @yield Configuration block using DSL
           def has_organizations(**options, &block)
@@ -111,9 +112,10 @@ module Organizations
           end
 
           def setup_personal_org_callback
-            after_create :create_personal_organization_if_configured, if: -> {
-              self.class.organization_settings[:create_personal_org]
-            }
+            # Callback that creates personal organization.
+            # The condition is checked inside the callback to ensure it's evaluated
+            # at the right time with the correct instance state.
+            after_create :create_personal_organization_if_configured
           end
 
           def setup_owner_deletion_guard
@@ -136,7 +138,14 @@ module Organizations
           end
 
           # Enable/disable personal organization creation on signup
-          # @param value [Boolean]
+          # @param value [Boolean, Proc] Boolean or proc that receives the user instance
+          #
+          # @example Boolean (backward-compatible)
+          #   create_personal_org true
+          #
+          # @example Proc for conditional creation
+          #   create_personal_org ->(user) { !user.skip_personal_organization }
+          #
           def create_personal_org(value)
             @settings[:create_personal_org] = value
           end
@@ -499,9 +508,41 @@ module Organizations
             org.send_invite_to!(email, invited_by: self, role: role)
           end
 
+          # Extension seam for personal organization creation.
+          # Override this method in your User model to implement custom logic.
+          #
+          # @return [Boolean] true if a personal organization should be created
+          #
+          # @example Skip personal org for invited signups
+          #   class User < ApplicationRecord
+          #     has_organizations
+          #     attr_accessor :skip_personal_organization
+          #
+          #     def should_create_personal_organization?
+          #       return false if skip_personal_organization
+          #       super
+          #     end
+          #   end
+          #
+          def should_create_personal_organization?
+            setting = self.class.organization_settings[:create_personal_org]
+
+            case setting
+            when Proc
+              setting.call(self)
+            else
+              !!setting
+            end
+          end
+
           private
 
           def create_personal_organization_if_configured
+            # Check condition inside callback (not via `if:` option) to ensure
+            # proper evaluation of instance state, including singleton methods
+            # and dynamically-set attributes.
+            return unless should_create_personal_organization?
+
             org_name = Organizations.configuration.resolve_default_organization_name(self)
             create_organization!(org_name)
           rescue StandardError => e
@@ -512,7 +553,7 @@ module Organizations
           def prevent_deletion_while_owning_organizations
             return unless memberships.where(role: "owner").exists?
 
-            errors.add(:base, "Cannot delete a user who still owns organizations. Transfer ownership first.")
+            errors.add(:base, "Cannot delete a user who still owns organizations. Transfer ownership or delete those organizations first.")
             throw(:abort)
           end
         end

data/lib/organizations/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Organizations
-  VERSION = "0.4.1"
+  VERSION = "0.4.2"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: organizations
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.4.2
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2026-03-17 00:00:00.000000000 Z
+date: 2026-03-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -103,6 +103,11 @@ files:
 - app/views/organizations/invitation_mailer/invitation_email.html.erb
 - app/views/organizations/invitation_mailer/invitation_email.text.erb
 - config/routes.rb
+- context7.json
+- docs/organizations-invitation-accept-create-account.webp
+- docs/organizations-member-permissions.webp
+- docs/organizations-switcher.webp
+- docs/organizations-team-members.webp
 - gemfiles/rails_7.2.gemfile
 - gemfiles/rails_8.1.gemfile
 - lib/generators/organizations/install/install_generator.rb