[SIP-198] Homepage Layout Extensions

## [SIP-198] Proposal for Homepage Layout Extensions

> **Note**: This proposal is intended as an input for the Generic Page Builder. The architecture described here is designed to align with and contribute to the broader vision outlined in SIP-151. Interfaces and patterns are indicative rather than final, and should be refined through collaboration with the Extensions SDK maintainers.

---

### Motivation

**The core idea is not to add another animal to the zoo, but to extend what we already have.**

The current Superset homepage presents fixed sections (Recent Dashboards, Recent Charts, Recent Activity, Saved Queries) that cannot be customized without modifying the core frontend codebase. This creates friction for:

1. **Enterprise organizations** that want to display organization-specific content, KPIs, or prioritized dashboards
2. **End users** with different workflows who would prefer to see content relevant to their role
3. **Administrators** who want to add announcements, documentation links, or custom widgets

**Community Demand**

This is a frequently requested feature:
- [Discussion #18571](https://github.com/apache/superset/discussions/18571) - Customize Home Page option
- [Discussion #33761](https://github.com/apache/superset/discussions/33761) - Customizing the Welcome Page

**Why Homepage First?**

Homepage is an ideal proving ground for layout extensions because:
- **Simpler than Dashboard**: No cross-filtering, no slice management, fewer edge cases
- **High community demand**: Frequently requested feature
- **Validates the pattern**: Success here paves the way for Dashboard component extensions

---

### Proposed Change

This SIP proposes Homepage customization as an **implementation of the Extensions SDK** (SIP-151), following the same `ViewContribution` pattern established by SQL Lab Extensions (SIP-177, PR #36644).

#### Alignment with Extensions Architecture

| SQL Lab Pattern | Homepage Equivalent |
|-----------------|---------------------|
| `sqllab.rightSidebar` | `homepage.sidebar` |
| `sqllab.panels` | `homepage.main` |
| `sqllab.editor` | `homepage.header` |
| `ExtensionsManager` | Same `ExtensionsManager` |

#### View Contributions

Following the SQL Lab pattern, we define Homepage regions as `ViewContribution`:

```typescript
export enum HomepageViewContribution {
Header = 'homepage.header',
Main = 'homepage.main',
Sidebar = 'homepage.sidebar',
}
```

#### Visual Layout

```
┌─────────────────────────────────────────────────────────────────┐
│ HEADER (homepage.header) │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Welcome Banner / Announcements │ │
│ └─────────────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────────┤
│ MAIN (homepage.main) │ SIDEBAR (homepage.sidebar) │
│ ┌───────────────────────────────┐ │ ┌─────────────────────────┐ │
│ │ Recent Dashboards │ │ │ Favorites │ │
│ ├───────────────────────────────┤ │ ├─────────────────────────┤ │
│ │ Recent Charts │ │ │ Quick Actions │ │
│ ├───────────────────────────────┤ │ └─────────────────────────┘ │
│ │ Activity │ Saved Queries │ │ │
│ └───────────────────────────────┘ │ │
└─────────────────────────────────────────────────────────────────┘
```

#### Interactive Demo

A working prototype demonstrating the proposed Homepage Builder is available here:

**[superset-homepage-builder-demo](https://github.com/EnxDev/superset-homepage-builder-demo)**

The demo showcases:
- Drag-and-drop widget reordering
- Widget configuration modal
- Add/remove widgets
- Preset layouts
- Edit mode toggle

#### Integration with ExtensionsManager

Components are registered through the existing `ExtensionsManager`:

```typescript
import { extensionsManager } from '@superset-ui/core';
import { HomepageViewContribution } from './contributions';

extensionsManager.register({
id: 'recent-dashboards',
viewId: HomepageViewContribution.Main,
component: RecentDashboards,
name: t('Recent Dashboards'),
configSchema: recentDashboardsConfigSchema,
defaultConfig: { limit: 6, showFavorites: true },
});
```

#### Built-in Components

The existing homepage sections become built-in extensions:

| Component ID | View Contribution | Description |
|--------------|-------------------|-------------|
| `welcome-banner` | `homepage.header` | Customizable welcome message |
| `recent-dashboards` | `homepage.main` | Recently accessed dashboards |
| `recent-charts` | `homepage.main` | Recently accessed charts |
| `recent-activity` | `homepage.main` | Activity feed |
| `saved-queries` | `homepage.main` | Saved SQL queries |
| `favorites` | `homepage.sidebar` | Favorited items |
| `markdown` | any | Custom Markdown content |

#### Configuration Storage

| Scope | Storage | Who Can Edit |
|-------|---------|--------------|
| Default | Code/Config | Developers |
| Global | Database | Admin |
| Role-based | Database | Admin |
| User | Database | User (if enabled) |

#### Toward a Generic Page Builder

As discussed with the Extensions working group, there's potential for a generic page builder serving both Homepage and Dashboards. This SIP focuses on Phase 1:

1. **Phase 1**: Implement Homepage extensions using current pattern ← *this SIP*
2. **Phase 2**: Extract common layout engine
3. **Phase 3**: Unify with Dashboard builder

---

### New or Changed Public Interfaces

#### REST API

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/v1/homepage/layout` | GET | Get effective layout for current user |
| `/api/v1/homepage/layout` | PUT | Save user's layout |
| `/api/v1/homepage/components` | GET | List available components |
| `/api/v1/homepage/layout/global` | GET/PUT | Admin: manage global layout |

#### Frontend

- `HomepageViewContribution` enum (new)
- Component registration via existing `ExtensionsManager`
- `HomepageComponentProps` interface for widget implementations

#### Configuration

- `HOMEPAGE_EXTENSIONS_ENABLED` feature flag in `superset_config.py`

---

### New Dependencies

No new third-party dependencies required. The implementation leverages existing Superset infrastructure:

| Package | Status | License | Notes |
|---------|--------|---------|-------|
| `react-dnd` | Already in use | MIT | Used by Dashboard builder |
| `@superset-ui/core` | Already in use | Apache 2.0 | ExtensionsManager |

---

### Migration Plan and Compatibility

#### Database Migrations

- New `homepage_layouts` table for storing layout configurations (scope, layout JSON, timestamps)
- No changes to existing tables

#### Backward Compatibility

- **No breaking changes**: Current homepage remains the default
- **Feature flag**: `HOMEPAGE_EXTENSIONS_ENABLED` controls activation
- **Gradual rollout**: Can be enabled per-organization
- **Existing bookmarks**: Homepage URLs remain unchanged

#### Rollback Strategy

- Feature flag can be disabled to revert to classic homepage
- Layout data preserved in database for re-activation

---

### Rejected Alternatives

| Alternative | Why Rejected |
|-------------|--------------|
| **Dashboard as Homepage** | Loses homepage-specific features (recent items, activity feed). Already possible via redirect but incomplete solution. |
| **Extend existing extension points only** | Current `welcome.*` points don't allow reordering or drag-drop. Insufficient flexibility for real customization. |
| **Homepage as Dashboard type** | Over-engineered. Dashboard infrastructure too heavyweight for homepage use cases. Confusing UX. |
| **Standalone system (not Extensions SDK)** | Creates "another animal in the zoo". Against PMC direction for unified Extensions architecture (SIP-151). |

---

### References

- [SIP-151: Vision for new Superset Plugins Architecture](https://github.com/apache/superset/issues/31932)
- [SIP-177: SQL Lab Extensions](https://github.com/apache/superset/issues/34162)
- [PR #36644: SQL Lab action extensions](https://github.com/apache/superset/pull/36644)
- [Discussion #18571: Customize Home Page option](https://github.com/apache/superset/discussions/18571)
- [Superset Extensions Project Board](https://github.com/orgs/apache/projects/544)

---

### Open Questions

1. **Generic Page Builder**: How should Homepage extensions align with the broader page builder vision?
2. **Component Sharing**: Can components be reused across `homepage.*` and `dashboard.*` contexts?
3. **Edit Mode**: Should Homepage have its own edit mode, or integrate with a unified page builder UI?