docs: add web share API implementation plan

docs/plans/2025-12-27-web-share-api.md

···
+# Web Share API Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Add share functionality for galleries and profiles using the Web Share API with clipboard fallback.
+
+**Architecture:** Create a shared utility service for share logic. Add share button to gallery engagement bar. Convert profile header ellipsis to action menu with Share option. Create toast component for clipboard feedback.
+
+**Tech Stack:** Lit, Web Share API, Clipboard API
+
+---
+
+## Task 1: Create Share Utility Service
+
+**Files:**
+- Create: `src/services/share.js`
+
+**Step 1: Create the share service**
+
+```javascript
+/**
+ * Share utility with Web Share API and clipboard fallback.
+ * Returns { success: boolean, method: 'share' | 'clipboard' }
+ */
+export async function share(url) {
+  // Try Web Share API first
+  if (navigator.share) {
+    try {
+      await navigator.share({ url });
+      return { success: true, method: 'share' };
+    } catch (err) {
+      // User cancelled or error - fall through to clipboard
+      if (err.name === 'AbortError') {
+        return { success: false, method: 'share' };
+      }
+    }
+  }
+
+  // Fallback to clipboard
+  try {
+    await navigator.clipboard.writeText(url);
+    return { success: true, method: 'clipboard' };
+  } catch (err) {
+    console.error('Failed to copy to clipboard:', err);
+    return { success: false, method: 'clipboard' };
+  }
+}
+```
+
+**Step 2: Commit**
+
+```bash
+git add src/services/share.js
+git commit -m "feat: add share utility service with Web Share API and clipboard fallback"
+```
+
+---
+
+## Task 2: Create Toast Component
+
+**Files:**
+- Create: `src/components/atoms/grain-toast.js`
+
+**Step 1: Create the toast component**
+
+```javascript
+import { LitElement, html, css } from 'lit';
+
+export class GrainToast extends LitElement {
+  static properties = {
+    message: { type: String },
+    _visible: { state: true }
+  };
+
+  static styles = css`
+    :host {
+      position: fixed;
+      bottom: calc(var(--nav-height, 56px) + var(--space-md));
+      left: 50%;
+      transform: translateX(-50%);
+      z-index: 1001;
+      pointer-events: none;
+    }
+    .toast {
+      background: var(--color-text-primary);
+      color: var(--color-bg-primary);
+      padding: var(--space-sm) var(--space-md);
+      border-radius: var(--border-radius);
+      font-size: var(--font-size-sm);
+      opacity: 0;
+      transition: opacity 0.2s;
+    }
+    .toast.visible {
+      opacity: 1;
+    }
+  `;
+
+  constructor() {
+    super();
+    this.message = '';
+    this._visible = false;
+  }
+
+  show(message, duration = 2000) {
+    this.message = message;
+    this._visible = true;
+    setTimeout(() => {
+      this._visible = false;
+    }, duration);
+  }
+
+  render() {
+    return html`
+      <div class="toast ${this._visible ? 'visible' : ''}">
+        ${this.message}
+      </div>
+    `;
+  }
+}
+
+customElements.define('grain-toast', GrainToast);
+```
+
+**Step 2: Commit**
+
+```bash
+git add src/components/atoms/grain-toast.js
+git commit -m "feat: add toast component for transient feedback"
+```
+
+---
+
+## Task 3: Add Share Button to Engagement Bar
+
+**Files:**
+- Modify: `src/components/organisms/grain-engagement-bar.js`
+
+**Step 1: Add share button and event**
+
+Update `grain-engagement-bar.js` to:
+1. Add a `url` property for the shareable URL
+2. Import the share utility and toast
+3. Add a share button (using existing `share` icon)
+4. Handle share with toast feedback for clipboard fallback
+
+```javascript
+import { LitElement, html, css } from 'lit';
+import { share } from '../../services/share.js';
+import '../molecules/grain-stat-count.js';
+import '../atoms/grain-icon.js';
+import '../atoms/grain-toast.js';
+
+export class GrainEngagementBar extends LitElement {
+  static properties = {
+    favoriteCount: { type: Number },
+    commentCount: { type: Number },
+    url: { type: String }
+  };
+
+  static styles = css`
+    :host {
+      display: flex;
+      align-items: center;
+      gap: var(--space-sm);
+      padding: var(--space-sm);
+    }
+    @media (min-width: 600px) {
+      :host {
+        padding-left: 0;
+        padding-right: 0;
+      }
+    }
+    .share-button {
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      background: none;
+      border: none;
+      padding: var(--space-sm);
+      margin: calc(-1 * var(--space-sm));
+      cursor: pointer;
+      color: var(--color-text-primary);
+      border-radius: var(--border-radius);
+      transition: opacity 0.2s;
+    }
+    .share-button:hover {
+      opacity: 0.7;
+    }
+    .share-button:active {
+      transform: scale(0.95);
+    }
+  `;
+
+  constructor() {
+    super();
+    this.favoriteCount = 0;
+    this.commentCount = 0;
+    this.url = '';
+  }
+
+  async #handleShare() {
+    const result = await share(this.url || window.location.href);
+    if (result.success && result.method === 'clipboard') {
+      this.shadowRoot.querySelector('grain-toast').show('Link copied');
+    }
+  }
+
+  render() {
+    return html`
+      <grain-stat-count
+        icon="heart"
+        count=${this.favoriteCount}
+      ></grain-stat-count>
+      <grain-stat-count
+        icon="comment"
+        count=${this.commentCount}
+      ></grain-stat-count>
+      <button class="share-button" type="button" aria-label="Share" @click=${this.#handleShare}>
+        <grain-icon name="share" size="16"></grain-icon>
+      </button>
+      <grain-toast></grain-toast>
+    `;
+  }
+}
+
+customElements.define('grain-engagement-bar', GrainEngagementBar);
+```
+
+**Step 2: Commit**
+
+```bash
+git add src/components/organisms/grain-engagement-bar.js
+git commit -m "feat: add share button to engagement bar"
+```
+
+---
+
+## Task 4: Pass URL to Engagement Bar in Gallery Detail
+
+**Files:**
+- Modify: `src/components/pages/grain-gallery-detail.js`
+
+**Step 1: Add url property to engagement bar**
+
+In `grain-gallery-detail.js`, update the `<grain-engagement-bar>` usage to pass the gallery URL:
+
+Find this line (~259):
+```html
+<grain-engagement-bar
+  favoriteCount=${this._gallery.favoriteCount}
+  commentCount=${this._gallery.commentCount}
+></grain-engagement-bar>
+```
+
+Replace with:
+```html
+<grain-engagement-bar
+  favoriteCount=${this._gallery.favoriteCount}
+  commentCount=${this._gallery.commentCount}
+  url=${window.location.href}
+></grain-engagement-bar>
+```
+
+**Step 2: Commit**
+
+```bash
+git add src/components/pages/grain-gallery-detail.js
+git commit -m "feat: pass gallery URL to engagement bar for sharing"
+```
+
+---
+
+## Task 5: Convert Profile Header Ellipsis to Action Menu
+
+**Files:**
+- Modify: `src/components/organisms/grain-profile-header.js`
+
+**Step 1: Add action dialog, share logic, and menu state**
+
+Update `grain-profile-header.js` to:
+1. Import share service, toast, and action dialog
+2. Add state for menu open
+3. Show ellipsis for ALL users (not just owner)
+4. Open action dialog with Share (for everyone) and Settings (for owner only)
+5. Handle share action with toast feedback
+
+```javascript
+import { LitElement, html, css } from 'lit';
+import { router } from '../../router.js';
+import { auth } from '../../services/auth.js';
+import { share } from '../../services/share.js';
+import '../atoms/grain-avatar.js';
+import '../atoms/grain-icon.js';
+import '../atoms/grain-toast.js';
+import '../molecules/grain-profile-stats.js';
+import '../organisms/grain-action-dialog.js';
+
+export class GrainProfileHeader extends LitElement {
+  static properties = {
+    profile: { type: Object },
+    _showFullscreen: { state: true },
+    _user: { state: true },
+    _menuOpen: { state: true }
+  };
+
+  static styles = css`
+    :host {
+      display: block;
+      padding: var(--space-md) var(--space-sm);
+    }
+    @media (min-width: 600px) {
+      :host {
+        padding-left: 0;
+        padding-right: 0;
+      }
+    }
+    .top-row {
+      display: flex;
+      align-items: flex-start;
+      gap: var(--space-md);
+      margin-bottom: var(--space-sm);
+    }
+    .right-column {
+      flex: 1;
+      min-width: 0;
+      padding-top: var(--space-xs);
+    }
+    .handle-row {
+      display: flex;
+      align-items: center;
+      gap: var(--space-sm);
+      margin-bottom: var(--space-xs);
+    }
+    .handle {
+      font-size: var(--font-size-lg);
+      font-weight: var(--font-weight-semibold);
+      color: var(--color-text-primary);
+    }
+    .name {
+      font-size: var(--font-size-sm);
+      color: var(--color-text-primary);
+      margin-bottom: var(--space-xs);
+    }
+    .bio {
+      font-size: var(--font-size-sm);
+      color: var(--color-text-secondary);
+      line-height: 1.4;
+      white-space: pre-wrap;
+      margin-top: var(--space-xs);
+    }
+    .avatar-button {
+      background: none;
+      border: none;
+      padding: 0;
+      cursor: pointer;
+    }
+    .fullscreen-overlay {
+      position: fixed;
+      top: 0;
+      bottom: 0;
+      left: 50%;
+      transform: translateX(-50%);
+      width: 100%;
+      max-width: var(--feed-max-width);
+      background: rgba(0, 0, 0, 0.9);
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      z-index: 1000;
+      cursor: pointer;
+    }
+    .fullscreen-overlay img {
+      max-width: 80%;
+      max-height: 80%;
+      border-radius: 50%;
+      object-fit: cover;
+    }
+    .menu-button {
+      background: none;
+      border: none;
+      padding: 0;
+      cursor: pointer;
+      color: var(--color-text-secondary);
+    }
+  `;
+
+  constructor() {
+    super();
+    this._showFullscreen = false;
+    this._user = auth.user;
+    this._menuOpen = false;
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+    this._unsubscribe = auth.subscribe(user => {
+      this._user = user;
+    });
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this._unsubscribe?.();
+  }
+
+  get #isOwnProfile() {
+    return this._user?.handle && this._user.handle === this.profile?.handle;
+  }
+
+  get #menuActions() {
+    const actions = [{ label: 'Share', action: 'share' }];
+    if (this.#isOwnProfile) {
+      actions.push({ label: 'Settings', action: 'settings' });
+    }
+    return actions;
+  }
+
+  #openMenu() {
+    this._menuOpen = true;
+  }
+
+  #closeMenu() {
+    this._menuOpen = false;
+  }
+
+  async #handleAction(e) {
+    const action = e.detail.action;
+    this._menuOpen = false;
+
+    if (action === 'settings') {
+      router.push('/settings');
+    } else if (action === 'share') {
+      const result = await share(window.location.href);
+      if (result.success && result.method === 'clipboard') {
+        this.shadowRoot.querySelector('grain-toast').show('Link copied');
+      }
+    }
+  }
+
+  #openFullscreen() {
+    this._showFullscreen = true;
+  }
+
+  #closeFullscreen() {
+    this._showFullscreen = false;
+  }
+
+  render() {
+    if (!this.profile) return null;
+
+    const { handle, displayName, description, avatarUrl, galleryCount, followerCount, followingCount } = this.profile;
+
+    return html`
+      ${this._showFullscreen ? html`
+        <div class="fullscreen-overlay" @click=${this.#closeFullscreen}>
+          <img src=${avatarUrl || ''} alt=${handle || ''}>
+        </div>
+      ` : ''}
+
+      <div class="top-row">
+        <button class="avatar-button" @click=${this.#openFullscreen}>
+          <grain-avatar
+            src=${avatarUrl || ''}
+            alt=${handle || ''}
+            size="lg"
+          ></grain-avatar>
+        </button>
+        <div class="right-column">
+          <div class="handle-row">
+            <span class="handle">${handle}</span>
+            <button class="menu-button" @click=${this.#openMenu}>
+              <grain-icon name="ellipsisVertical" size="20"></grain-icon>
+            </button>
+          </div>
+          ${displayName ? html`<div class="name">${displayName}</div>` : ''}
+          <grain-profile-stats
+            handle=${handle}
+            galleryCount=${galleryCount || 0}
+            followerCount=${followerCount || 0}
+            followingCount=${followingCount || 0}
+          ></grain-profile-stats>
+          ${description ? html`<div class="bio">${description}</div>` : ''}
+        </div>
+      </div>
+
+      <grain-action-dialog
+        ?open=${this._menuOpen}
+        .actions=${this.#menuActions}
+        @action=${this.#handleAction}
+        @close=${this.#closeMenu}
+      ></grain-action-dialog>
+
+      <grain-toast></grain-toast>
+    `;
+  }
+}
+
+customElements.define('grain-profile-header', GrainProfileHeader);
+```
+
+**Step 2: Commit**
+
+```bash
+git add src/components/organisms/grain-profile-header.js
+git commit -m "feat: convert profile ellipsis to action menu with share option"
+```
+
+---
+
+## Task 6: Manual Testing
+
+**Step 1: Test gallery share**
+
+1. Navigate to a gallery detail page
+2. Click the share button in the engagement bar
+3. On mobile: Native share sheet should appear
+4. On desktop (no Web Share): "Link copied" toast should appear, verify clipboard contains URL
+
+**Step 2: Test profile share**
+
+1. Navigate to any profile page
+2. Click the ellipsis menu
+3. Verify "Share" option appears for all users
+4. Verify "Settings" option only appears on your own profile
+5. Click "Share" and verify same behavior as gallery share
+
+**Step 3: Final commit**
+
+```bash
+git add -A
+git commit -m "feat: add web share API for galleries and profiles"
+```
+
+---
+
+## Summary
+
+| Task | Description |
+|------|-------------|
+| 1 | Create share utility service |
+| 2 | Create toast component |
+| 3 | Add share button to engagement bar |
+| 4 | Pass URL to engagement bar in gallery detail |
+| 5 | Convert profile header to action menu with share |
+| 6 | Manual testing |