magick-feature-flags 0.9.35 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5a2d57b267028e1f3d30a1a5dc4e540d6b254d41ea1b436f5ab0e25278c0f213
-  data.tar.gz: 0c1a022445c14e1534b312f4cfc71ec71b9a576d4b66a5d860323a480df79380
+  metadata.gz: b702af543d2f50e7f5b7ba6917ed318cff4e0b1fd82ef355a8aac757a18be75d
+  data.tar.gz: 8d68c5bb592755731f46a681a76d4b9fa092ddd5b46300042c8225fa6fffb90b
 SHA512:
-  metadata.gz: a0576cc8537ef6df5ff4ce95f973994a477936d94cde874b24945505139fbf411798fb54d100544f1848ad1b2388164b64a95421732daa33d753bcef7c14cce5
-  data.tar.gz: 803584894d4c2494c324df94613a80a34ca268f522ffabe36bc162e989ca25be8aaa9d1f919f10584e722b47863940a1610c6f7cbc75d6960b2070304e4efe55
+  metadata.gz: 21f49a8f8058dadddce614fa1e2766b385b6764ae7021e2a93ad6532edda4189d2a74bc6faeafb38f8dc1d4a980d9bc09c813836ee1e94f2381f2904f8b78bd6
+  data.tar.gz: 452eb3dbb5def24b61c89e5e1b08257a50b531df8834c2877fc1e926093a97c14c426a61be5cb3b61a41ab14d2a85bc061df9bd92229d8820f4452535dd1afe1

data/README.md

@@ -5,7 +5,7 @@ A performant and memory-efficient feature toggle gem for Ruby and Rails applicat
 ## Features
 
 - **Multiple Feature Types**: Boolean, string, and number feature flags
-- **Flexible Targeting**: Enable features for specific users, groups, roles, or percentages
+- **Flexible Targeting**: Enable features for specific users, groups, roles, tags, or percentages
 - **Dual Backend**: Memory adapter (fast) with Redis fallback (persistent)
 - **Rails Integration**: Seamless integration with Rails, including request store caching
 - **DSL Support**: Define features in a Ruby DSL file (`config/features.rb`)
@@ -45,18 +45,15 @@ This will create `config/initializers/magick.rb` with a basic configuration.
 
 ### ActiveRecord Adapter (Optional)
 
-If you want to use ActiveRecord as a persistent storage backend, generate the migration:
+If you want to use ActiveRecord as a persistent storage backend, you **must** generate and run the migration:
 
 ```bash
 rails generate magick:active_record
-```
-
-This will create a migration file that creates the `magick_features` table. Then run:
-
-```bash
 rails db:migrate
 ```
 
+This will create a migration file that creates the `magick_features` table. **The adapter will not auto-create the table** - you must run migrations.
+
 **Note:** The ActiveRecord adapter is optional and only needed if you want database-backed feature flags. The gem works perfectly fine with just the memory adapter or Redis adapter.
 
 ## Configuration
@@ -137,7 +134,8 @@ end
 Magick.register_feature(:new_dashboard,
   type: :boolean,
   default_value: false,
-  description: "New dashboard UI"
+  description: "New dashboard UI",
+  group: "UI"  # Optional: group features for organization
 )
 
 # Register a string feature
@@ -175,6 +173,10 @@ feature.enable_for_group("beta_testers")
 # Enable for specific role
 feature.enable_for_role("admin")
 
+# Enable for specific tag
+feature.enable_for_tag("premium")
+feature.enable_for_tag("beta")
+
 # Enable for percentage of users (consistent)
 feature.enable_percentage_of_users(25) # 25% of users
 
@@ -217,12 +219,28 @@ end
 Magick.enabled_for?(:feature, user)           # ActiveRecord object
 Magick.enabled_for?(:feature, { id: 123, role: 'admin' })  # Hash
 Magick.enabled_for?(:feature, 123)            # Simple ID
+
+# Tag targeting - tags are automatically extracted from user objects
+user = User.find(123)  # User has tags association
+feature.enable_for_tag('premium')
+Magick.enabled_for?(:feature, user)  # Checks user.tags automatically
+
+# Or explicitly pass tags
+Magick.enabled?(:feature, tags: user.tags.map(&:id))
+Magick.enabled?(:feature, tags: ['premium', 'beta'])
+
+# Tags are extracted from:
+# - user.tags (ActiveRecord association)
+# - user.tag_ids (array of IDs)
+# - user.tag_names (array of names)
+# - hash[:tags], hash[:tag_ids], hash[:tag_names]
 ```
 
 The `enabled_for?` method automatically extracts:
 - `user_id` from `id` or `user_id` attribute
 - `group` from `group` attribute
 - `role` from `role` attribute
+- `tags` from `tags` association, `tag_ids`, or `tag_names` methods/attributes
 - `ip_address` from `ip_address` attribute
 - All other attributes for custom attribute matching
 
@@ -236,6 +254,8 @@ result = feature.enable                    # => true
 result = feature.disable                   # => true
 result = feature.enable_for_user(123)      # => true
 result = feature.enable_for_group('beta')  # => true
+result = feature.enable_for_role('admin')  # => true
+result = feature.enable_for_tag('premium') # => true
 result = feature.enable_percentage_of_users(25)  # => true
 result = feature.set_value(true)          # => true
 ```
@@ -460,7 +480,7 @@ The ActiveRecord adapter provides database-backed persistent storage for feature
 
 **Setup:**
 
-1. Generate the migration:
+1. **Generate and run the migration** (required):
    ```bash
    rails generate magick:active_record
    rails db:migrate
@@ -469,8 +489,11 @@ The ActiveRecord adapter provides database-backed persistent storage for feature
    **With UUID primary keys:**
    ```bash
    rails generate magick:active_record --uuid
+   rails db:migrate
    ```
 
+   **Important:** The adapter will **not** auto-create the table. You must run migrations before using the ActiveRecord adapter. If the table doesn't exist, the adapter will raise a clear error with instructions.
+
 2. Configure in `config/initializers/magick.rb`:
    ```ruby
    Magick.configure do
@@ -480,8 +503,6 @@ The ActiveRecord adapter provides database-backed persistent storage for feature
    end
    ```
 
-The adapter automatically creates the `magick_features` table if it doesn't exist, but using the generator is recommended for production applications.
-
 **PostgreSQL Support:**
 
 The generator automatically detects PostgreSQL and uses `jsonb` for the `data` column, providing:
@@ -521,12 +542,16 @@ Magick includes a web-based Admin UI for managing feature flags. It's a Rails En
 
 **Setup:**
 
-1. Configure roles (optional) for targeting management in `config/initializers/magick.rb`:
+1. Configure roles and tags (optional) for targeting management in `config/initializers/magick.rb`:
 
 ```ruby
 Rails.application.config.after_initialize do
   Magick::AdminUI.configure do |config|
     config.available_roles = ['admin', 'user', 'manager', 'guest']
+    # Tags can be configured as an array or lambda (for dynamic loading)
+    config.available_tags = -> { Tag.all }  # Lambda loads tags dynamically
+    # Or as a static array:
+    # config.available_tags = ['premium', 'beta', 'vip']
   end
 end
 ```
@@ -562,10 +587,38 @@ Once mounted, visit `/magick` in your browser to access the Admin UI.
 - **Enable/Disable**: Quickly enable or disable features globally
 - **Targeting Management**: Configure targeting rules through a user-friendly interface:
   - **Role Targeting**: Select roles from a configured list (checkboxes)
+  - **Tag Targeting**: Select tags from a dynamically loaded list (checkboxes)
   - **User Targeting**: Enter user IDs (comma-separated)
   - **Visual Display**: See all active targeting rules with badges
 - **Edit Features**: Update feature values (boolean, string, number) directly from the UI
 - **Statistics**: View performance metrics and usage statistics for each feature
+- **Feature Grouping**: Organize features into groups for easier management and filtering
+- **Filtering**: Filter features by group, name, or description
+
+**Feature Grouping:**
+
+Features can be organized into groups for easier management and filtering:
+
+1. **Setting Groups**:
+   - Set a group when registering a feature in code:
+     ```ruby
+     Magick.register_feature(:new_payment_flow,
+       type: :boolean,
+       default_value: false,
+       group: 'Payment',
+       description: "New payment processing flow"
+     )
+     ```
+   - Or set/update groups via the Admin UI when editing a feature
+
+2. **Filtering by Group**:
+   - Use the group dropdown in the Admin UI to filter features by group
+   - Combine group filtering with search to find specific features quickly
+
+3. **Benefits**:
+   - Organize features by functional area (e.g., "Authentication", "Payment", "UI")
+   - Quickly find related features
+   - Better organization for large feature flag sets
 
 **Targeting Management:**
 
@@ -576,14 +629,21 @@ The Admin UI provides a comprehensive targeting interface:
    - Select multiple roles using checkboxes
    - Roles are automatically added/removed when checkboxes are toggled
 
-2. **User Targeting**:
+2. **Tag Targeting**:
+   - Configure available tags via `Magick::AdminUI.configure` (supports lambda for dynamic loading)
+   - Tags are loaded dynamically each time the page loads (if using lambda)
+   - Select multiple tags using checkboxes
+   - Tags are automatically added/removed when checkboxes are toggled
+   - Tags can be ActiveRecord objects (IDs are stored) or simple strings
+
+3. **User Targeting**:
    - Enter user IDs as comma-separated values (e.g., `123, 456, 789`)
    - Add or remove users dynamically
    - Clear all user targeting by leaving the field empty
 
-3. **Visual Feedback**:
+4. **Visual Feedback**:
    - All targeting rules are displayed as badges in the feature details view
-   - Easy to see which roles/users have access to each feature
+   - Easy to see which roles/tags/users have access to each feature
 
 **Routes:**
 

data/app/controllers/magick/adminui/features_controller.rb

@@ -9,7 +9,7 @@ module Magick
       before_action :set_feature, only: %i[show edit update enable disable enable_for_user enable_for_role disable_for_role update_targeting]
 
       # Make route helpers available in views via magick_admin_ui helper
-      helper_method :magick_admin_ui, :available_roles, :partially_enabled?
+      helper_method :magick_admin_ui, :available_roles, :available_tags, :partially_enabled?
 
       def magick_admin_ui
         Magick::AdminUI::Engine.routes.url_helpers
@@ -19,6 +19,10 @@ module Magick
         Magick::AdminUI.config.available_roles || []
       end
 
+      def available_tags
+        Magick::AdminUI.config.tags
+      end
+
       def partially_enabled?(feature)
         targeting = feature.instance_variable_get(:@targeting) || {}
         targeting.any? && !targeting.empty?
@@ -26,6 +30,24 @@ module Magick
 
       def index
         @features = Magick.features.values
+
+        # Filter by group if provided
+        if params[:group].present?
+          @features = @features.select { |f| f.group == params[:group] }
+        end
+
+        # Filter by search query (name or description)
+        if params[:search].present?
+          search_term = params[:search].downcase
+          @features = @features.select do |f|
+            f.name.downcase.include?(search_term) ||
+            (f.display_name && f.display_name.downcase.include?(search_term)) ||
+            (f.description && f.description.downcase.include?(search_term))
+          end
+        end
+
+        # Get all available groups for filter dropdown
+        @available_groups = Magick.features.values.map(&:group).compact.uniq.sort
       end
 
       def show
@@ -35,6 +57,11 @@ module Magick
       end
 
       def update
+        # Update group if provided
+        if params.key?(:group)
+          @feature.set_group(params[:group])
+        end
+
         if @feature.type == :boolean
           # For boolean features, checkbox sends 'true' when checked, nothing when unchecked
           # Rails form helpers handle this - if checkbox is unchecked, params[:value] will be nil
@@ -111,6 +138,21 @@ module Magick
           @feature.enable_for_role(role) if role.present?
         end
 
+        # Handle tags - always clear existing and set new ones
+        # Rails checkboxes don't send unchecked values, so we need to check what was sent
+        current_tags = current_targeting[:tag].is_a?(Array) ? current_targeting[:tag] : (current_targeting[:tag] ? [current_targeting[:tag]] : [])
+        selected_tags = Array(targeting_params[:tags]).reject(&:blank?)
+
+        # Disable tags that are no longer selected
+        (current_tags - selected_tags).each do |tag|
+          @feature.disable_for_tag(tag) if tag.present?
+        end
+
+        # Enable newly selected tags
+        (selected_tags - current_tags).each do |tag|
+          @feature.enable_for_tag(tag) if tag.present?
+        end
+
         # Handle user IDs - replace existing user targeting
         if targeting_params[:user_ids].present?
           user_ids = targeting_params[:user_ids].split(',').map(&:strip).reject(&:blank?)

data/app/views/layouts/application.html.erb

@@ -332,6 +332,100 @@
       box-shadow: 0 0 0 2px rgba(52, 152, 219, 0.1);
     }
 
+    /* Tags Search Interface */
+    .tags-search-container {
+      display: flex;
+      align-items: center;
+      gap: 12px;
+      margin-bottom: 12px;
+    }
+    .tags-search-input {
+      flex: 1;
+      padding: 10px 12px;
+      border: 1px solid #ddd;
+      border-radius: 4px;
+      font-size: 14px;
+      transition: border-color 0.2s, box-shadow 0.2s;
+    }
+    .tags-search-input:focus {
+      outline: none;
+      border-color: #3498db;
+      box-shadow: 0 0 0 2px rgba(52, 152, 219, 0.1);
+    }
+    .tags-count {
+      font-size: 13px;
+      color: #666;
+      white-space: nowrap;
+    }
+    .tags-checkbox-container {
+      max-height: 300px;
+      overflow-y: auto;
+      border: 1px solid #e0e0e0;
+      border-radius: 4px;
+      padding: 12px;
+      background: #fafafa;
+      display: flex;
+      flex-direction: column;
+      gap: 8px;
+    }
+    .tags-checkbox-container::-webkit-scrollbar {
+      width: 8px;
+    }
+    .tags-checkbox-container::-webkit-scrollbar-track {
+      background: #f1f1f1;
+      border-radius: 4px;
+    }
+    .tags-checkbox-container::-webkit-scrollbar-thumb {
+      background: #ccc;
+      border-radius: 4px;
+    }
+    .tags-checkbox-container::-webkit-scrollbar-thumb:hover {
+      background: #999;
+    }
+    .tag-checkbox-label {
+      display: inline-flex;
+      align-items: center;
+      cursor: pointer;
+      padding: 6px 8px;
+      border-radius: 4px;
+      transition: background-color 0.2s;
+    }
+    .tag-checkbox-label:hover {
+      background-color: #f0f0f0;
+    }
+    .tag-checkbox-label.hidden {
+      display: none;
+    }
+    .tag-checkbox {
+      margin-right: 8px;
+      cursor: pointer;
+    }
+    .tag-checkbox-text {
+      font-size: 14px;
+      color: #333;
+      user-select: none;
+    }
+    .tag-checkbox:checked + .tag-checkbox-text {
+      font-weight: 500;
+      color: #1976d2;
+    }
+    .tag-checkbox:checked ~ .tag-checkbox-text {
+      font-weight: 500;
+      color: #1976d2;
+    }
+    /* Highlight checked labels */
+    .tag-checkbox-label:has(.tag-checkbox:checked) {
+      background-color: #e3f2fd;
+    }
+    /* Fallback for browsers without :has() support */
+    .tag-checkbox-label.checked {
+      background-color: #e3f2fd;
+    }
+    .tag-checkbox-label.checked .tag-checkbox-text {
+      font-weight: 500;
+      color: #1976d2;
+    }
+
     /* Mobile Responsive */
     @media (max-width: 768px) {
       .container {
@@ -419,6 +513,17 @@
         min-width: 100px;
         font-size: 16px; /* Prevents zoom on iOS */
       }
+      .tags-search-container {
+        flex-direction: column;
+        align-items: stretch;
+      }
+      .tags-count {
+        text-align: right;
+        margin-top: 4px;
+      }
+      .tags-checkbox-container {
+        max-height: 200px;
+      }
     }
 
     /* Tablet */
@@ -528,6 +633,176 @@
         });
       });
     })();
+
+    // Tags Search Filter
+    (function() {
+      const searchInput = document.getElementById('tags_search');
+      const checkboxContainer = document.getElementById('tags_checkbox_container');
+      const visibleCount = document.getElementById('tags_visible_count');
+      const totalCount = document.getElementById('tags_total_count');
+
+      if (!searchInput || !checkboxContainer || !visibleCount || !totalCount) return;
+
+      function filterTags() {
+        const searchTerm = searchInput.value.toLowerCase().trim();
+        const labels = Array.from(checkboxContainer.querySelectorAll('.tag-checkbox-label'));
+        let visibleLabels = [];
+        let hiddenLabels = [];
+
+        labels.forEach(label => {
+          const tagName = label.getAttribute('data-tag-name') || '';
+          const tagId = label.getAttribute('data-tag-id') || '';
+          const tagText = label.querySelector('.tag-checkbox-text')?.textContent.toLowerCase() || '';
+          const checkbox = label.querySelector('.tag-checkbox');
+          const isChecked = checkbox && checkbox.checked;
+
+          // Match against tag name, id, or display text
+          const matches = !searchTerm ||
+                         tagName.includes(searchTerm) ||
+                         tagId.includes(searchTerm) ||
+                         tagText.includes(searchTerm);
+
+          if (matches) {
+            label.classList.remove('hidden');
+            visibleLabels.push({ label: label, checked: isChecked });
+          } else {
+            label.classList.add('hidden');
+            hiddenLabels.push(label);
+          }
+        });
+
+        // Sort visible labels: checked first, then unchecked
+        visibleLabels.sort((a, b) => {
+          if (a.checked && !b.checked) return -1;
+          if (!a.checked && b.checked) return 1;
+          return 0;
+        });
+
+        // Reorder DOM: checked items first, then unchecked, then hidden
+        visibleLabels.forEach(({ label }) => {
+          checkboxContainer.appendChild(label);
+        });
+        hiddenLabels.forEach(label => {
+          checkboxContainer.appendChild(label);
+        });
+
+        visibleCount.textContent = visibleLabels.length;
+      }
+
+      // Filter on input
+      searchInput.addEventListener('input', filterTags);
+
+      // Clear search on Escape key
+      searchInput.addEventListener('keydown', function(e) {
+        if (e.key === 'Escape') {
+          searchInput.value = '';
+          filterTags();
+          searchInput.blur();
+        }
+      });
+
+      // Update checked state classes and reorder on change
+      checkboxContainer.querySelectorAll('.tag-checkbox').forEach(checkbox => {
+        function updateCheckedClass() {
+          const label = checkbox.closest('.tag-checkbox-label');
+          if (checkbox.checked) {
+            label.classList.add('checked');
+            label.setAttribute('data-checked', 'true');
+          } else {
+            label.classList.remove('checked');
+            label.setAttribute('data-checked', 'false');
+          }
+          // Reorder after change to keep checked items on top
+          filterTags();
+        }
+        checkbox.addEventListener('change', updateCheckedClass);
+        updateCheckedClass(); // Initial state
+      });
+    })();
+
+    // Roles Search Filter
+    (function() {
+      const searchInput = document.getElementById('roles_search');
+      const checkboxContainer = document.getElementById('roles_checkbox_container');
+      const visibleCount = document.getElementById('roles_visible_count');
+      const totalCount = document.getElementById('roles_total_count');
+
+      if (!searchInput || !checkboxContainer || !visibleCount || !totalCount) return;
+
+      function filterRoles() {
+        const searchTerm = searchInput.value.toLowerCase().trim();
+        const labels = Array.from(checkboxContainer.querySelectorAll('.tag-checkbox-label'));
+        let visibleLabels = [];
+        let hiddenLabels = [];
+
+        labels.forEach(label => {
+          const roleName = label.getAttribute('data-role-name') || '';
+          const roleText = label.querySelector('.tag-checkbox-text')?.textContent.toLowerCase() || '';
+          const checkbox = label.querySelector('.tag-checkbox');
+          const isChecked = checkbox && checkbox.checked;
+
+          // Match against role name or display text
+          const matches = !searchTerm ||
+                         roleName.includes(searchTerm) ||
+                         roleText.includes(searchTerm);
+
+          if (matches) {
+            label.classList.remove('hidden');
+            visibleLabels.push({ label: label, checked: isChecked });
+          } else {
+            label.classList.add('hidden');
+            hiddenLabels.push(label);
+          }
+        });
+
+        // Sort visible labels: checked first, then unchecked
+        visibleLabels.sort((a, b) => {
+          if (a.checked && !b.checked) return -1;
+          if (!a.checked && b.checked) return 1;
+          return 0;
+        });
+
+        // Reorder DOM: checked items first, then unchecked, then hidden
+        visibleLabels.forEach(({ label }) => {
+          checkboxContainer.appendChild(label);
+        });
+        hiddenLabels.forEach(label => {
+          checkboxContainer.appendChild(label);
+        });
+
+        visibleCount.textContent = visibleLabels.length;
+      }
+
+      // Filter on input
+      searchInput.addEventListener('input', filterRoles);
+
+      // Clear search on Escape key
+      searchInput.addEventListener('keydown', function(e) {
+        if (e.key === 'Escape') {
+          searchInput.value = '';
+          filterRoles();
+          searchInput.blur();
+        }
+      });
+
+      // Update checked state classes and reorder on change
+      checkboxContainer.querySelectorAll('.tag-checkbox').forEach(checkbox => {
+        function updateCheckedClass() {
+          const label = checkbox.closest('.tag-checkbox-label');
+          if (checkbox.checked) {
+            label.classList.add('checked');
+            label.setAttribute('data-checked', 'true');
+          } else {
+            label.classList.remove('checked');
+            label.setAttribute('data-checked', 'false');
+          }
+          // Reorder after change to keep checked items on top
+          filterRoles();
+        }
+        checkbox.addEventListener('change', updateCheckedClass);
+        updateCheckedClass(); // Initial state
+      });
+    })();
   </script>
 </body>
 </html>

data/app/views/magick/adminui/features/edit.html.erb

@@ -18,6 +18,12 @@
       <input type="text" value="<%= @feature.type.to_s.capitalize %>" disabled>
     </div>
 
+    <div class="form-group">
+      <label>Group</label>
+      <%= text_field_tag 'group', @feature.group, placeholder: 'e.g., Authentication, Payment, UI', class: 'form-control' %>
+      <small style="color: #999;">Optional: Group features together for easier organization and filtering</small>
+    </div>
+
     <div class="form-group">
       <label>Current Value</label>
       <% if @feature.type == :boolean %>
@@ -64,11 +70,22 @@
       <% if roles_list.any? %>
         <div class="form-group">
           <label>Enable for Roles</label>
-          <div style="display: flex; flex-direction: column; gap: 8px;">
-            <% roles_list.each do |role| %>
-              <label style="display: inline-flex; align-items: center; cursor: pointer;">
-                <%= check_box_tag 'targeting[roles][]', role, current_roles.include?(role.to_s), id: "role_#{role}" %>
-                <span style="margin-left: 8px;"><%= role.to_s.humanize %></span>
+          <div class="tags-search-container">
+            <input type="text" id="roles_search" class="tags-search-input" placeholder="Search roles... (e.g., admin, manager)" autocomplete="off">
+            <div class="tags-count" id="roles_count">
+              <span id="roles_visible_count"><%= roles_list.length %></span> of <span id="roles_total_count"><%= roles_list.length %></span> roles
+            </div>
+          </div>
+          <div class="tags-checkbox-container" id="roles_checkbox_container">
+            <%# Render checked roles first, then unchecked %>
+            <% checked_roles, unchecked_roles = roles_list.partition { |role| current_roles.include?(role.to_s) } %>
+            <% (checked_roles + unchecked_roles).each do |role| %>
+              <% role_name = role.to_s %>
+              <% role_display = role.to_s.humanize %>
+              <% is_checked = current_roles.include?(role.to_s) %>
+              <label class="tag-checkbox-label <%= 'checked' if is_checked %>" data-role-name="<%= role_name.downcase %>" data-checked="<%= is_checked %>">
+                <%= check_box_tag 'targeting[roles][]', role, is_checked, id: "role_#{role}", class: 'tag-checkbox' %>
+                <span class="tag-checkbox-text"><%= role_display %></span>
               </label>
             <% end %>
           </div>
@@ -81,6 +98,42 @@
         </div>
       <% end %>
 
+      <% current_tags = targeting[:tag].is_a?(Array) ? targeting[:tag] : (targeting[:tag] ? [targeting[:tag]] : []) %>
+      <% tags_list = available_tags %>
+      <% if tags_list.any? %>
+        <div class="form-group">
+          <label>Enable for Tags</label>
+          <div class="tags-search-container">
+            <input type="text" id="tags_search" class="tags-search-input" placeholder="Search tags... (e.g., test, MONITOR)" autocomplete="off">
+            <div class="tags-count" id="tags_count">
+              <span id="tags_visible_count"><%= tags_list.length %></span> of <span id="tags_total_count"><%= tags_list.length %></span> tags
+            </div>
+          </div>
+          <div class="tags-checkbox-container" id="tags_checkbox_container">
+            <%# Render checked tags first, then unchecked %>
+            <% checked_tags, unchecked_tags = tags_list.partition do |tag|
+                 tag_id = tag.respond_to?(:id) ? tag.id.to_s : tag.to_s
+                 current_tags.include?(tag_id.to_s)
+               end %>
+            <% (checked_tags + unchecked_tags).each do |tag| %>
+              <% tag_id = tag.respond_to?(:id) ? tag.id.to_s : tag.to_s %>
+              <% tag_name = tag.respond_to?(:name) ? tag.name : (tag.respond_to?(:to_s) ? tag.to_s : tag_id) %>
+              <% is_checked = current_tags.include?(tag_id.to_s) %>
+              <label class="tag-checkbox-label <%= 'checked' if is_checked %>" data-tag-name="<%= tag_name.downcase %>" data-tag-id="<%= tag_id.downcase %>" data-checked="<%= is_checked %>">
+                <%= check_box_tag 'targeting[tags][]', tag_id, is_checked, id: "tag_#{tag_id}", class: 'tag-checkbox' %>
+                <span class="tag-checkbox-text"><%= tag_name %></span>
+              </label>
+            <% end %>
+          </div>
+          <small style="color: #999;">Select tags that should have access to this feature. Tags are loaded dynamically from your configuration.</small>
+        </div>
+      <% else %>
+        <div class="alert alert-info">
+          <p>No tags configured. Add tags via DSL:</p>
+          <code>Magick::AdminUI.configure { |config| config.available_tags = -> { Tag.all } }</code>
+        </div>
+      <% end %>
+
       <div class="form-group">
         <label>Enable for User IDs</label>
         <div class="user-ids-input-container">

data/app/views/magick/adminui/features/index.html.erb

@@ -6,6 +6,26 @@
     </div>
   </div>
 
+  <!-- Filtering UI -->
+  <div style="padding: 16px; border-bottom: 1px solid #e0e0e0; background: #f9f9f9;">
+    <%= form_with url: magick_admin_ui.features_path, method: :get, local: true, style: "display: flex; gap: 12px; flex-wrap: wrap; align-items: flex-end;" do |f| %>
+      <div style="flex: 1; min-width: 200px;">
+        <label for="search" style="display: block; margin-bottom: 4px; font-weight: 500;">Search</label>
+        <%= text_field_tag :search, params[:search], placeholder: "Search by name or description...", class: 'form-control', style: "width: 100%;" %>
+      </div>
+      <div style="flex: 0 0 180px;">
+        <label for="group" style="display: block; margin-bottom: 4px; font-weight: 500;">Group</label>
+        <%= select_tag :group, options_for_select([['All Groups', '']] + @available_groups.map { |g| [g, g] }, params[:group]), class: 'form-control', style: "width: 100%;" %>
+      </div>
+      <div style="flex: 0 0 auto;">
+        <%= submit_tag 'Filter', class: 'btn btn-primary btn-sm', style: "height: 38px;" %>
+        <% if params[:search].present? || params[:group].present? %>
+          <%= link_to 'Clear', magick_admin_ui.features_path, class: 'btn btn-secondary btn-sm', style: "height: 38px;" %>
+        <% end %>
+      </div>
+    <% end %>
+  </div>
+
   <% if @features.empty? %>
     <div class="empty-state">
       <h3>No features found</h3>
@@ -16,6 +36,7 @@
       <thead>
         <tr>
           <th>Name</th>
+          <th>Group</th>
           <th>Type</th>
           <th>Status</th>
           <th>Value</th>
@@ -31,6 +52,13 @@
               <br>
               <small style="color: #999;"><%= feature.name %></small>
             </td>
+            <td data-label="Group">
+              <% if feature.group.present? %>
+                <span class="badge badge-info"><%= feature.group %></span>
+              <% else %>
+                <em style="color: #999;">—</em>
+              <% end %>
+            </td>
             <td data-label="Type">
               <span class="badge badge-info">
                 <%= feature.type.to_s.capitalize %>

data/app/views/magick/adminui/features/show.html.erb

@@ -18,6 +18,14 @@
         <span class="badge badge-info"><%= @feature.type.to_s.capitalize %></span>
       </div>
     </div>
+    <% if @feature.group.present? %>
+      <div class="detail-item">
+        <div class="detail-label">Group</div>
+        <div class="detail-value">
+          <span class="badge badge-info"><%= @feature.group %></span>
+        </div>
+      </div>
+    <% end %>
     <div class="detail-item">
       <div class="detail-label">Status</div>
       <div class="detail-value">

data/lib/magick/admin_ui.rb

@@ -17,13 +17,21 @@ module Magick
       end
 
       class Configuration
-        attr_accessor :theme, :brand_name, :require_role, :available_roles
+        attr_accessor :theme, :brand_name, :require_role, :available_roles, :available_tags
 
         def initialize
           @theme = :light
           @brand_name = 'Magick'
           @require_role = nil
           @available_roles = [] # Can be populated via DSL: admin_ui { roles ['admin', 'user', 'manager'] }
+          @available_tags = nil # Can be array or lambda: -> { Tag.all }
+        end
+
+        # Get available tags, calling lambda if needed
+        def tags
+          return [] if @available_tags.nil?
+          return @available_tags.call if @available_tags.respond_to?(:call)
+          Array(@available_tags)
         end
       end
     end

data/lib/magick/dsl.rb

@@ -32,6 +32,10 @@ module Magick
       Magick[feature_name].enable_for_role(role_name)
     end
 
+    def enable_for_tag(feature_name, tag_name)
+      Magick[feature_name].enable_for_tag(tag_name)
+    end
+
     def enable_percentage(feature_name, percentage, type: :users)
       feature = Magick[feature_name]
       case type

data/lib/magick/feature.rb

@@ -8,7 +8,7 @@ module Magick
     VALID_TYPES = %i[boolean string number].freeze
     VALID_STATUSES = %i[active inactive deprecated].freeze
 
-    attr_reader :name, :type, :status, :default_value, :description, :display_name, :adapter_registry
+    attr_reader :name, :type, :status, :default_value, :description, :display_name, :group, :adapter_registry
 
     def initialize(name, adapter_registry, **options)
       @name = name.to_s
@@ -18,6 +18,7 @@ module Magick
       @default_value = options.fetch(:default_value, default_for_type)
       @description = options[:description]
       @display_name = options[:name] || options[:display_name]
+      @group = options[:group]
       @targeting = {}
       @dependencies = options[:dependencies] ? Array(options[:dependencies]) : []
       @stored_value_initialized = false # Track if @stored_value has been explicitly set
@@ -88,6 +89,18 @@ module Magick
     end
 
     def check_enabled(context = {})
+      # Extract context from user object if provided
+      # This allows Magick.enabled?(:feature, user: player) to work
+      if context[:user]
+        extracted = extract_context_from_object(context[:user])
+        # Merge extracted context, but don't override explicit values already in context
+        extracted.each do |key, value|
+          context[key] = value unless context.key?(key)
+        end
+        # Remove :user key after extraction to avoid confusion
+        context.delete(:user)
+      end
+
       # Fast path: check status first
       return false if status == :inactive
       return false if status == :deprecated && !context[:allow_deprecated]
@@ -110,17 +123,14 @@ module Magick
 
         # Check user/group/role/percentage targeting
         targeting_result = check_targeting(context)
-        if targeting_result.nil?
-          # Targeting doesn't match - return false
-          return false
-        else
-          # Targeting matches - for boolean features, return true directly
-          # For string/number features, still check the value
-          if type == :boolean
-            return true
-          end
-          # For string/number, continue to check value below
-        end
+        return false if targeting_result.nil?
+        # Targeting doesn't match - return false
+
+        # Targeting matches - for boolean features, return true directly
+        # For string/number features, still check the value
+        return true if type == :boolean
+        # For string/number, continue to check value below
+
       end
 
       # Get value and check based on type
@@ -169,23 +179,22 @@ module Magick
         # If targeting doesn't match (returns nil), continue to return default value
         unless targeting_result.nil?
           # Targeting matches - return stored value (or load it if not initialized)
-          if @stored_value_initialized
-            return @stored_value
+          return @stored_value if @stored_value_initialized
+
+          # Load from adapter
+          loaded_value = load_value_from_adapter
+          if loaded_value.nil?
+            # Value not found in adapter, use default and cache it
+            @stored_value = default_value
+            @stored_value_initialized = true
+            return default_value
           else
-            # Load from adapter
-            loaded_value = load_value_from_adapter
-            if loaded_value.nil?
-              # Value not found in adapter, use default and cache it
-              @stored_value = default_value
-              @stored_value_initialized = true
-              return default_value
-            else
-              # Value found in adapter, use it and mark as initialized
-              @stored_value = loaded_value
-              @stored_value_initialized = true
-              return loaded_value
-            end
+            # Value found in adapter, use it and mark as initialized
+            @stored_value = loaded_value
+            @stored_value_initialized = true
+            return loaded_value
           end
+
         end
         # Targeting doesn't match - return default value
         return default_value
@@ -243,6 +252,16 @@ module Magick
       true
     end
 
+    def enable_for_tag(tag_name)
+      enable_targeting(:tag, tag_name)
+      true
+    end
+
+    def disable_for_tag(tag_name)
+      disable_targeting(:tag, tag_name)
+      true
+    end
+
     def enable_percentage_of_users(percentage)
       @targeting[:percentage_users] = percentage.to_f
       save_targeting
@@ -405,6 +424,7 @@ module Magick
       adapter_registry.set(name, 'default_value', default_value)
       adapter_registry.set(name, 'description', description) if description
       adapter_registry.set(name, 'display_name', display_name) if display_name
+      adapter_registry.set(name, 'group', group) if group
       @stored_value = value
       @stored_value_initialized = true # Mark as initialized
 
@@ -516,6 +536,22 @@ module Magick
       true
     end
 
+    def set_group(group_name)
+      if group_name.nil? || group_name.to_s.strip.empty?
+        @group = nil
+        # Clear group from adapter by setting to empty string (adapters handle this)
+        adapter_registry.set(name, 'group', nil)
+      else
+        @group = group_name.to_s.strip
+        adapter_registry.set(name, 'group', @group)
+      end
+
+      # Update registered feature instance if it exists
+      Magick.features[name].instance_variable_set(:@group, @group) if Magick.features.key?(name)
+
+      true
+    end
+
     def delete
       adapter_registry.delete(name)
       @stored_value = nil
@@ -541,6 +577,7 @@ module Magick
         registered.instance_variable_set(:@status, @status)
         registered.instance_variable_set(:@description, @description)
         registered.instance_variable_set(:@display_name, @display_name)
+        registered.instance_variable_set(:@group, @group)
         registered.instance_variable_set(:@targeting, @targeting.dup)
         registered.instance_variable_set(:@_targeting_empty, @_targeting_empty)
         registered.instance_variable_set(:@_perf_metrics_enabled, @_perf_metrics_enabled)
@@ -576,7 +613,7 @@ module Magick
       # Update local targeting empty cache for performance
       @_targeting_empty = targeting.empty?
 
-      # Note: We don't need to explicitly publish cache invalidation here because:
+      # NOTE: We don't need to explicitly publish cache invalidation here because:
       # 1. adapter_registry.set already publishes cache invalidation (synchronously for async Redis updates)
       # 2. Publishing twice causes duplicate reloads in other processes
       # 3. The set method handles both sync and async Redis updates correctly
@@ -619,6 +656,10 @@ module Magick
         @display_name = display_name_value if display_name_value
       end
 
+      # Load group from adapter (can be set via DSL or Admin UI)
+      group_value = adapter_registry.get(name, 'group')
+      @group = group_value if group_value
+
       targeting_value = adapter_registry.get(name, 'targeting')
       if targeting_value.is_a?(Hash)
         # Normalize keys to symbols and handle nested structures
@@ -636,9 +677,8 @@ module Magick
       # The features.rb file is the source of truth for metadata
       # This ensures metadata is always up-to-date even if feature already exists
       adapter_registry.set(name, 'description', @description) if @description
-      return unless @display_name
-
-      adapter_registry.set(name, 'display_name', @display_name)
+      adapter_registry.set(name, 'display_name', @display_name) if @display_name
+      adapter_registry.set(name, 'group', @group) if @group
     end
 
     def load_value_from_adapter
@@ -681,6 +721,14 @@ module Magick
         return true if role_list.include?(context[:role].to_s)
       end
 
+      # Check tag targeting
+      if context[:tags] && target[:tag]
+        context_tags = Array(context[:tags]).map(&:to_s)
+        target_tags = target[:tag].is_a?(Array) ? target[:tag].map(&:to_s) : [target[:tag].to_s]
+        # Return true if any context tag matches any target tag
+        return true if (context_tags & target_tags).any?
+      end
+
       # Check percentage of users (consistent based on user_id)
       if context[:user_id] && target[:percentage_users]
         percentage = target[:percentage_users].to_f
@@ -806,10 +854,13 @@ module Magick
         context[:group] = object[:group] || object['group']
         context[:role] = object[:role] || object['role']
         context[:ip_address] = object[:ip_address] || object['ip_address']
+        # Extract tags from hash
+        tags = object[:tags] || object['tags'] || object[:tag_ids] || object['tag_ids'] || object[:tag_names] || object['tag_names']
+        context[:tags] = Array(tags).map(&:to_s) if tags
         # Include all other attributes for custom attribute matching
         object.each do |key, value|
-          next if %i[user_id id group role ip_address].include?(key.to_sym)
-          next if %w[user_id id group role ip_address].include?(key.to_s)
+          next if %i[user_id id group role ip_address tags tag_ids tag_names].include?(key.to_sym)
+          next if %w[user_id id group role ip_address tags tag_ids tag_names].include?(key.to_s)
 
           context[key.to_sym] = value
         end
@@ -820,10 +871,32 @@ module Magick
         context[:role] = object.role if object.respond_to?(:role)
         context[:ip_address] = object.ip_address if object.respond_to?(:ip_address)
 
+        # Extract tags from object - try multiple common patterns
+        tags = nil
+        if object.respond_to?(:tags)
+          tags = object.tags
+          # Handle ActiveRecord associations - convert to array if needed
+          tags = tags.to_a if tags.respond_to?(:to_a) && !tags.is_a?(Array)
+        elsif object.respond_to?(:tag_ids)
+          tags = object.tag_ids
+        elsif object.respond_to?(:tag_names)
+          tags = object.tag_names
+        end
+
+        # Normalize tags to array of strings
+        if tags
+          context[:tags] = if tags.respond_to?(:map) && tags.respond_to?(:each)
+                             # ActiveRecord association or array
+                             tags.map { |tag| tag.respond_to?(:id) ? tag.id.to_s : tag.to_s }
+                           else
+                             Array(tags).map(&:to_s)
+                           end
+        end
+
         # For ActiveRecord objects, include all attributes
         if object.respond_to?(:attributes)
           object.attributes.each do |key, value|
-            next if %w[id user_id group role ip_address].include?(key.to_s)
+            next if %w[id user_id group role ip_address tags tag_ids tag_names].include?(key.to_s)
 
             context[key.to_sym] = value
           end

data/lib/magick/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Magick
-  VERSION = '0.9.35'
+  VERSION = '1.0.0'
 end

data/lib/magick.rb

@@ -90,7 +90,7 @@ module Magick
 
       if block.arity.zero?
         # New DSL style - calls apply! automatically
-        ConfigDSL.configure(&block)
+        Magick::ConfigDSL.configure(&block)
       else
         # Old style - need to manually reapply Redis tracking after configuration
         yield self

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: magick-feature-flags
 version: !ruby/object:Gem::Version
-  version: 0.9.35
+  version: 1.0.0
 platform: ruby
 authors:
 - Andrew Lobanov
@@ -43,14 +43,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.22'
+        version: '3.8'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.22'
+        version: '3.8'
 - !ruby/object:Gem::Dependency
   name: activerecord
   requirement: !ruby/object:Gem::Requirement
@@ -77,14 +77,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.6'
+        version: '2.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.6'
+        version: '2.0'
 description: Magick is a better free version of Flipper feature-toggle gem. It is
   absolutely performant and memory efficient (by my opinion).
 email:
@@ -160,7 +160,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.0.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="