Justin Edmund b3979008ae Apple Music API

2025-06-13 21:22:39 -04:00

6.9 KiB

Raw Permalink Blame History

Product Requirements Document: URL Embed Functionality

Overview

This PRD outlines the implementation of URL paste functionality in the Editor that allows users to choose between displaying URLs as rich embed cards or simple links.

Background

Currently, the Editor supports various content types including text, images, and code blocks. Adding URL embed functionality will enhance the content creation experience by allowing users to share links with rich previews that include titles, descriptions, and images from the linked content.

Goals

Enable users to paste URLs and automatically convert them to rich embed cards
Provide flexibility to display URLs as either embed cards or simple links
Maintain consistency with existing UI/UX patterns
Ensure performance with proper loading states and error handling

User Stories

As a content creator, I want to paste a URL and have it automatically display as a rich preview card so that my content is more engaging.
As a content creator, I want to be able to choose between an embed card and a simple link so that I have control over how my content appears.
As a content creator, I want to edit or remove URL embeds after adding them so that I can correct mistakes or update content.
As a reader, I want to see rich previews of linked content so that I can decide whether to click through.

Functional Requirements

URL Detection and Conversion

Automatic Detection: When a user pastes a plain URL (e.g., https://example.com), the system should:
- Create a regular text link initially
- Display a dropdown menu next to the cursor with the option to "Convert to embed"
- If the user selects "Convert to embed", replace the link with an embed placeholder and fetch metadata
- If the user dismisses the dropdown or continues typing, keep it as a regular link
Manual Entry: Users should be able to manually add URL embeds through:
- Toolbar button (Insert → Link)
- Slash command (/url-embed)
- Direct input in placeholder

Embed Card Display

Metadata Fetching: The system should fetch OpenGraph metadata including:
- Title
- Description
- Preview image
- Site name
- Favicon
Card Layout: Display fetched metadata in a visually appealing card format that includes:
- Preview image (if available)
- Title (linked to URL)
- Description (truncated if too long)
- Site name and favicon
Fallback: If metadata fetching fails, display a simple card with the URL

User Interactions

In-Editor Actions:
- Refresh metadata
- Open link in new tab
- Remove embed
- Convert between embed and link
Loading States: Show spinner while fetching metadata
Error Handling: Display user-friendly error messages

Content Rendering

Editor View: Full interactive embed with action buttons
Published View: Static card with clickable elements
Responsive Design: Cards should adapt to different screen sizes

Technical Implementation

Architecture

TipTap Extensions:
- UrlEmbed: Main node extension for URL detection and schema
- UrlEmbedPlaceholder: Temporary node during loading
- UrlEmbedExtended: Final node with metadata
Components:
- UrlEmbedPlaceholder.svelte: Loading/input UI
- UrlEmbedExtended.svelte: Rich preview card
API Integration:
- Utilize existing /api/og-metadata endpoint
- Implement caching to reduce redundant fetches

Data Model

interface UrlEmbedNode {
	type: 'urlEmbed'
	attrs: {
		url: string
		title?: string
		description?: string
		image?: string
		siteName?: string
		favicon?: string
	}
}

UI/UX Specifications

Visual Design

Match existing LinkCard component styling
Use established color variables and spacing
Maintain consistency with overall site design

Interaction Patterns

Paste Flow:
- User pastes URL
- URL appears as regular link text
- Dropdown menu appears next to cursor with "Convert to embed" option
- If user selects "Convert to embed":
  - Link is replaced with placeholder showing spinner
  - Metadata loads and card renders
  - User can interact with card
- If user dismisses dropdown:
  - URL remains as regular link
Manual Entry Flow:
- User clicks Insert → Link or types /url-embed
- Input field appears
- User enters URL and presses Enter
- Same loading/rendering flow as paste

Performance Considerations

Lazy Loading: Only fetch metadata when URL is added
Caching: Cache fetched metadata to avoid redundant API calls
Timeout: Implement reasonable timeout for metadata fetching
Image Optimization: Consider lazy loading preview images

Security Considerations

URL Validation: Validate URLs before fetching metadata
Content Sanitization: Sanitize fetched metadata to prevent XSS
CORS Handling: Properly handle cross-origin requests

Success Metrics

Adoption Rate: Percentage of posts using URL embeds
Error Rate: Frequency of metadata fetch failures
Performance: Average time to fetch and display metadata
User Satisfaction: Feedback on embed functionality

Future Enhancements

Custom Previews: Allow manual editing of metadata
Platform-Specific Embeds: Special handling for YouTube, Twitter, etc.
Embed Templates: Different card styles for different content types

Timeline

Phase 1: Core Functionality

Status: In Progress

Completed Tasks:

Create TipTap extension for URL detection (UrlEmbed.ts)
Create placeholder component for loading state (UrlEmbedPlaceholder.svelte)
Create extended component for rich preview (UrlEmbedExtended.svelte)
Integrate with existing /api/og-metadata endpoint
Add URL embed to Insert menu in toolbar
Add URL embed to slash commands
Implement loading states and error handling
Style embed cards to match existing LinkCard design
Add content rendering for published posts

Remaining Tasks:

Implement paste detection with dropdown menu
Create dropdown component for "Convert to embed" option
Add convert between embed/link functionality
Add keyboard shortcuts for dropdown interaction
Implement caching for metadata fetches
Add tests for URL detection and conversion
Update documentation

Phase 2: Platform-Specific Embeds

Status: Future

YouTube video embeds with player
Twitter/X post embeds
Instagram post embeds
GitHub repository/gist embeds

Phase 3: Advanced Customization