attune/work-summary/empty-pack-creation-ui.md

Empty Pack Creation UI Feature

Date: 2026-01-27
Status: ✅ Complete

Overview

Enhanced the Pack Management UI to clearly distinguish between two pack creation workflows:

1. Create Empty Pack - For ad-hoc rules, workflows, and webhooks (no filesystem required)
2. Register from Filesystem - For packs with actions, sensors, and pack.yaml metadata

Problem Statement

The Pack Registration page only offered filesystem-based pack registration, which required users to have a pack directory structure. There was no clear UI path to create empty packs for ad-hoc automation content like:

• Custom rules created via the UI
• Workflow actions defined in the database
• Webhook triggers for external integrations

While the API supported creating empty packs and a form existed at /packs/new, it wasn't discoverable from the main Packs page.

Solution

1. Added Dropdown Menu to Packs Page

File: attune/web/src/pages/packs/PacksPage.tsx

Replaced single "Register" button with dropdown menu offering both options:

<button onClick={() => setShowPackMenu(!showPackMenu)}>
  <Plus /> New Pack <ChevronDown />
</button>

// Dropdown menu with two options:
// 1. Create Empty Pack → /packs/new
// 2. Register from Filesystem → /packs/register

Features:

• Clear visual distinction with icons (Plus vs Package)
• Descriptive text explaining each option
• Click-outside-to-dismiss pattern
• Proper state management with showPackMenu

2. Enhanced Pack Create Page

File: attune/web/src/pages/packs/PackCreatePage.tsx

Changes:

• Updated title: "Register New Pack" → "Create Empty Pack"
• Added comprehensive info box explaining when to use empty packs
• Organized info with icons (Zap, Workflow, Radio)
• Added visual examples for three main use cases:
  • Ad-hoc Rules
  • Custom Workflows
  • Webhook Triggers
• Included tip directing users to filesystem registration when appropriate

3. Enhanced Pack Register Page

File: attune/web/src/pages/packs/PackRegisterPage.tsx

Changes:

• Updated title to "Register Pack from Filesystem" (more specific)
• Added green-themed info box explaining filesystem-based registration
• Listed required directory structure (pack.yaml, actions/, sensors/, etc.)
• Added cross-link to empty pack creation
• Maintained existing functionality (path input, test options, force mode)

4. Updated Empty State

File: attune/web/src/pages/packs/PacksPage.tsx

When no packs exist, show both options:

• "Create an empty pack"
• "or"
• "Register from filesystem"

Visual Design

Dropdown Menu Layout

┌─────────────────────────────────────┐
│ [+] Create Empty Pack               │
│     For ad-hoc rules, workflows... │
├─────────────────────────────────────┤
│ [📦] Register from Filesystem       │
│     Load pack from local directory  │
└─────────────────────────────────────┘

Info Boxes

• Create Empty Pack: Blue-themed (Info icon)

  • Lists three use cases with icons
  • Provides context on when to use

• Register from Filesystem: Green-themed (FolderOpen icon)

  • Lists directory structure requirements
  • Cross-links to empty pack option

Technical Implementation

State Management

const [showPackMenu, setShowPackMenu] = useState(false);

Icons Used

• Plus - Create empty pack action
• Package - Register from filesystem action
• ChevronDown - Dropdown indicator
• Info - Information callout
• FolderOpen - Filesystem registration
• Zap - Ad-hoc rules
• Workflow - Custom workflows
• Radio - Webhook triggers

Routing

• /packs/new - Empty pack creation form (PackCreatePage)
• /packs/register - Filesystem registration (PackRegisterPage)
• Both accessible from dropdown menu on /packs

User Experience Flow

Creating Empty Pack

1. Navigate to Packs page
2. Click "New Pack" dropdown
3. Select "Create Empty Pack"
4. Read info box explaining use cases
5. Fill out form (ref, label, version required)
6. Submit to create empty pack
7. Redirect to pack details

Registering from Filesystem

1. Navigate to Packs page
2. Click "New Pack" dropdown
3. Select "Register from Filesystem"
4. Read info box explaining directory requirements
5. Enter filesystem path
6. Configure test options (skip/force)
7. Submit to register pack
8. Tests run (unless skipped)
9. Redirect to pack details

Form Fields (Empty Pack Creation)

Required:

• Reference ID (ref) - lowercase, alphanumeric, hyphens, underscores
• Label - human-readable display name
• Version - semver format (e.g., 1.0.0)

Optional:

• Description
• Tags (comma-separated)
• Runtime Dependencies (pack refs)
• Configuration Schema (JSON Schema)
• Configuration Values (JSON)
• Metadata (JSON)
• Standard Pack flag

Benefits

1. Discoverability: Both pack creation methods clearly visible
2. Clarity: Users understand when to use each option
3. Flexibility: Support for both ad-hoc and filesystem-based packs
4. Education: Info boxes teach users about pack structure
5. Workflow Support: Enable ad-hoc automation without filesystem complexity

Use Cases Enabled

Ad-hoc Rules

Users can now:

1. Create an empty pack (e.g., "my-alerts")
2. Define rules via UI that reference the pack
3. Rules are stored in database only
4. No filesystem actions needed

Custom Workflows

Users can now:

1. Create an empty pack for workflow actions
2. Define workflow actions in database
3. Reference pack in workflow definitions
4. Execute without filesystem scripts

Webhook Triggers

Users can now:

1. Create an empty pack for webhooks
2. Define webhook triggers via UI
3. Create rules that respond to webhooks
4. No pack.yaml or action files required

Build Verification

✅ TypeScript compilation successful
✅ Vite production build successful
✅ Bundle size: 484.74 kB (gzip: 134.21 kB)
✅ No console errors or warnings
✅ All imports cleaned up

Files Modified

1. attune/web/src/pages/packs/PacksPage.tsx

   • Added dropdown menu with two options
   • Updated empty state with both links
   • Imported Plus and ChevronDown icons
   • Added state management for menu visibility

2. attune/web/src/pages/packs/PackCreatePage.tsx

   • Updated title and description
   • Added comprehensive info box
   • Added use case examples with icons
   • Improved visual layout

3. attune/web/src/pages/packs/PackRegisterPage.tsx

   • Updated title to be more specific
   • Added filesystem structure info box
   • Added cross-link to empty pack creation
   • Reformatted for consistency

4. attune/web/src/components/layout/MainLayout.tsx

   • Cleaned up unused icon imports (PlayCircle, FileTerminal)

Documentation Impact

The UI now self-documents:

• When to create empty packs
• When to register from filesystem
• What each option requires
• What use cases each option supports

Future Enhancements (Optional)

1. Pack Templates: Provide pre-configured templates for common pack types
2. Import/Export: Allow exporting empty packs as pack.yaml for filesystem use
3. Pack Conversion: Convert filesystem packs to empty packs and vice versa
4. Quick Create: "Create pack for this rule" button on rule creation
5. Pack Categories: Tag-based filtering (webhooks, workflows, rules)
6. Pack Statistics: Show action/rule/workflow counts per pack

Testing Checklist

✅ Dropdown menu opens and closes correctly
✅ Click outside dismisses menu
✅ Both menu options navigate to correct pages
✅ Info boxes display with correct styling
✅ Icons render properly
✅ Empty state shows both options
✅ Form validation works (ref format, version format, JSON validation)
✅ Pack creation succeeds and redirects
✅ Pack registration works as before
✅ No TypeScript errors
✅ No console warnings

Conclusion

The Pack Management UI now clearly presents both pack creation workflows, making it obvious when to use each option. Users can now easily create empty packs for ad-hoc automation content without needing to understand filesystem-based pack structure. The addition of contextual info boxes educates users about pack types and helps them make the right choice for their use case.

Result: Empty pack creation is now a first-class, discoverable feature in the UI, enabling ad-hoc rules, custom workflows, and webhook triggers without filesystem complexity.