@commonpub/layer 0.1.0

package/composables/useEngagement.ts

@@ -0,0 +1,196 @@
+/**
+ * Reusable composable for content engagement actions (like, bookmark, share).
+ * Handles optimistic updates with rollback on API failure.
+ */
+export interface ContentViewData {
+  id: string;
+  type: string;
+  title: string;
+  slug: string;
+  subtitle: string | null;
+  description: string | null;
+  content: unknown;
+  coverImageUrl: string | null;
+  category: string | null;
+  difficulty: string | null;
+  buildTime: string | null;
+  estimatedCost: string | null;
+  status: string;
+  visibility: string;
+  isFeatured: boolean;
+  seoDescription: string | null;
+  previewToken: string | null;
+  parts: Array<{
+    id: string;
+    name: string;
+    description?: string;
+    quantity: number;
+    url?: string;
+    price?: number;
+    currency?: string;
+    category?: string;
+    required: boolean;
+    productId?: string;
+  }> | null;
+  sections: Array<{
+    id: string;
+    title: string;
+    anchor: string;
+    type: string;
+    content?: unknown;
+  }> | null;
+  viewCount: number;
+  likeCount: number;
+  commentCount: number;
+  forkCount: number;
+  publishedAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+  licenseType: string | null;
+  series: string | null;
+  estimatedMinutes: number | null;
+  tags: Array<{ id: string; name: string; slug: string }>;
+  author: {
+    id: string;
+    username: string;
+    displayName: string | null;
+    avatarUrl: string | null;
+    bio?: string | null;
+    headline?: string | null;
+    verified?: boolean;
+    org?: string;
+    articleCount?: number;
+    followerCount?: number;
+    totalViews?: number;
+    postCount?: number;
+  };
+  // Optional fields that may come from enriched responses
+  readTime?: string;
+  buildCount?: number;
+  bookmarkCount?: number;
+  githubUrl?: string;
+  license?: string;
+  hardwarePrimary?: string;
+  hardwareSecondary?: string;
+  hardwareTertiary?: string;
+  community?: { name: string; slug: string; description: string | null };
+  related?: Array<{ id: string; type: string; slug: string; title: string; readTime?: string; viewCount?: number }>;
+  seriesPart?: number;
+  seriesTitle?: string;
+  seriesTotalParts?: number;
+  seriesPrev?: { title: string; url: string };
+  seriesNext?: { title: string; url: string };
+}
+
+export interface EngagementOptions {
+  contentId: Ref<string | undefined>;
+  contentType: Ref<string>;
+  /** When set, likes federate to the remote instance instead of acting locally */
+  federatedContentId?: Ref<string | undefined>;
+}
+
+export function useEngagement(opts: EngagementOptions) {
+  const { contentId, contentType, federatedContentId } = opts;
+  const liked = ref(false);
+  const bookmarked = ref(false);
+  const likeCount = ref(0);
+
+  const isFederated = computed(() => !!federatedContentId?.value);
+
+  function setInitialState(isLiked: boolean, isBookmarked: boolean, likes: number): void {
+    liked.value = isLiked;
+    bookmarked.value = isBookmarked;
+    likeCount.value = likes;
+  }
+
+  async function toggleLike(): Promise<void> {
+    if (!contentId.value) return;
+    const prev = liked.value;
+    const prevCount = likeCount.value;
+    liked.value = !liked.value;
+    likeCount.value += liked.value ? 1 : -1;
+
+    try {
+      if (isFederated.value) {
+        await $fetch('/api/federation/like', {
+          method: 'POST',
+          body: { federatedContentId: federatedContentId!.value },
+        });
+      } else {
+        await $fetch('/api/social/like', {
+          method: 'POST',
+          body: { targetType: contentType.value, targetId: contentId.value },
+        });
+      }
+    } catch {
+      liked.value = prev;
+      likeCount.value = prevCount;
+    }
+  }
+
+  async function toggleBookmark(): Promise<void> {
+    if (!contentId.value) return;
+    // Bookmarks are local-only — skip for federated content (no local record to target)
+    if (isFederated.value) return;
+    const prev = bookmarked.value;
+    bookmarked.value = !bookmarked.value;
+
+    try {
+      await $fetch('/api/social/bookmark', {
+        method: 'POST',
+        body: { targetType: contentType.value, targetId: contentId.value },
+      });
+    } catch {
+      bookmarked.value = prev;
+    }
+  }
+
+  async function share(): Promise<void> {
+    if (!contentId.value) return;
+    if (navigator.share) {
+      try {
+        await navigator.share({
+          url: window.location.href,
+        });
+      } catch {
+        // User cancelled or not supported
+      }
+    } else {
+      await navigator.clipboard.writeText(window.location.href);
+    }
+  }
+
+  /** Fetch actual liked/bookmarked state from server (call onMounted) */
+  async function fetchInitialState(likes: number): Promise<void> {
+    likeCount.value = likes;
+    if (!contentId.value) return;
+    // Skip state fetch for federated content — no local like/bookmark records
+    if (isFederated.value) return;
+    try {
+      const [likeRes, bmRes] = await Promise.all([
+        $fetch<{ liked: boolean }>('/api/social/like', {
+          params: { targetType: contentType.value, targetId: contentId.value },
+        }).catch(() => ({ liked: false })),
+        $fetch<{ bookmarked: boolean }>('/api/social/bookmark', {
+          params: { targetType: contentType.value, targetId: contentId.value },
+        }).catch(() => ({ bookmarked: false })),
+      ]);
+      liked.value = likeRes.liked;
+      bookmarked.value = bmRes.bookmarked;
+    } catch {
+      // Non-critical — default to false
+    }
+  }
+
+  return {
+    liked,
+    bookmarked,
+    likeCount,
+    isFederated,
+    setInitialState,
+    fetchInitialState,
+    toggleLike,
+    toggleBookmark,
+    share,
+  };
+}

package/composables/useFeatures.ts

@@ -0,0 +1,33 @@
+// Feature flag composable — reactive access to enabled features
+
+export interface FeatureFlags {
+  content: boolean;
+  social: boolean;
+  hubs: boolean;
+  docs: boolean;
+  video: boolean;
+  contests: boolean;
+  learning: boolean;
+  explainers: boolean;
+  federation: boolean;
+  admin: boolean;
+}
+
+export function useFeatures() {
+  const config = useRuntimeConfig();
+  const flags = config.public.features as FeatureFlags;
+
+  return {
+    features: flags,
+    content: computed(() => flags.content),
+    social: computed(() => flags.social),
+    hubs: computed(() => flags.hubs),
+    docs: computed(() => flags.docs),
+    video: computed(() => flags.video),
+    contests: computed(() => flags.contests),
+    learning: computed(() => flags.learning),
+    explainers: computed(() => flags.explainers),
+    federation: computed(() => flags.federation),
+    admin: computed(() => flags.admin),
+  };
+}

package/composables/useFederation.ts

@@ -0,0 +1,72 @@
+import type { RemoteActorProfile } from '@commonpub/server';
+
+export function useFederation() {
+  const searchResult = ref<RemoteActorProfile | null>(null);
+  const searchLoading = ref(false);
+  const searchError = ref<string | null>(null);
+
+  async function searchRemoteUser(query: string): Promise<RemoteActorProfile | null> {
+    searchLoading.value = true;
+    searchError.value = null;
+    searchResult.value = null;
+
+    try {
+      const result = await $fetch<RemoteActorProfile | null>('/api/federation/search', {
+        method: 'POST',
+        body: { query },
+      });
+      searchResult.value = result;
+      return result;
+    } catch (err: unknown) {
+      const msg = err instanceof Error ? err.message : 'Search failed';
+      searchError.value = msg;
+      return null;
+    } finally {
+      searchLoading.value = false;
+    }
+  }
+
+  async function followRemoteUser(actorUri: string): Promise<boolean> {
+    try {
+      await $fetch('/api/federation/follow', {
+        method: 'POST',
+        body: { actorUri },
+      });
+      // Update search result to reflect pending follow
+      if (searchResult.value && searchResult.value.actorUri === actorUri) {
+        searchResult.value = { ...searchResult.value, isFollowPending: true };
+      }
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async function unfollowRemoteUser(actorUri: string): Promise<boolean> {
+    try {
+      await $fetch('/api/federation/unfollow', {
+        method: 'POST',
+        body: { actorUri },
+      });
+      if (searchResult.value && searchResult.value.actorUri === actorUri) {
+        searchResult.value = {
+          ...searchResult.value,
+          isFollowing: false,
+          isFollowPending: false,
+        };
+      }
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  return {
+    searchResult,
+    searchLoading,
+    searchError,
+    searchRemoteUser,
+    followRemoteUser,
+    unfollowRemoteUser,
+  };
+}

package/composables/useJsonLd.ts

@@ -0,0 +1,183 @@
+/** Composable for adding JSON-LD structured data to pages */
+
+interface JsonLdArticle {
+  type: 'article';
+  title: string;
+  description: string;
+  url: string;
+  imageUrl?: string;
+  authorName: string;
+  authorUrl: string;
+  publishedAt: string;
+  updatedAt: string;
+}
+
+interface JsonLdHowTo {
+  type: 'howto';
+  title: string;
+  description: string;
+  url: string;
+  imageUrl?: string;
+  authorName: string;
+  authorUrl: string;
+  difficulty?: string;
+  estimatedTime?: string;
+  estimatedCost?: string;
+  steps?: Array<{ name: string; text: string }>;
+}
+
+interface JsonLdCourse {
+  type: 'course';
+  title: string;
+  description: string;
+  url: string;
+  imageUrl?: string;
+  providerName: string;
+  providerUrl: string;
+}
+
+interface JsonLdVideo {
+  type: 'video';
+  title: string;
+  description: string;
+  url: string;
+  thumbnailUrl?: string;
+  uploadDate: string;
+  duration?: string;
+}
+
+interface JsonLdPerson {
+  type: 'person';
+  name: string;
+  url: string;
+  imageUrl?: string;
+  description?: string;
+  jobTitle?: string;
+}
+
+interface JsonLdOrganization {
+  type: 'organization';
+  name: string;
+  url: string;
+  logoUrl?: string;
+  description?: string;
+}
+
+type JsonLdInput =
+  | JsonLdArticle
+  | JsonLdHowTo
+  | JsonLdCourse
+  | JsonLdVideo
+  | JsonLdPerson
+  | JsonLdOrganization;
+
+function buildJsonLd(input: JsonLdInput): Record<string, unknown> {
+  switch (input.type) {
+    case 'article':
+      return {
+        '@context': 'https://schema.org',
+        '@type': 'Article',
+        headline: input.title,
+        description: input.description,
+        url: input.url,
+        ...(input.imageUrl ? { image: input.imageUrl } : {}),
+        author: {
+          '@type': 'Person',
+          name: input.authorName,
+          url: input.authorUrl,
+        },
+        datePublished: input.publishedAt,
+        dateModified: input.updatedAt,
+      };
+
+    case 'howto':
+      return {
+        '@context': 'https://schema.org',
+        '@type': 'HowTo',
+        name: input.title,
+        description: input.description,
+        url: input.url,
+        ...(input.imageUrl ? { image: input.imageUrl } : {}),
+        author: {
+          '@type': 'Person',
+          name: input.authorName,
+          url: input.authorUrl,
+        },
+        ...(input.estimatedTime ? { totalTime: input.estimatedTime } : {}),
+        ...(input.estimatedCost
+          ? { estimatedCost: { '@type': 'MonetaryAmount', value: input.estimatedCost, currency: 'USD' } }
+          : {}),
+        ...(input.steps?.length
+          ? {
+              step: input.steps.map((s, i) => ({
+                '@type': 'HowToStep',
+                position: i + 1,
+                name: s.name,
+                text: s.text,
+              })),
+            }
+          : {}),
+      };
+
+    case 'course':
+      return {
+        '@context': 'https://schema.org',
+        '@type': 'Course',
+        name: input.title,
+        description: input.description,
+        url: input.url,
+        ...(input.imageUrl ? { image: input.imageUrl } : {}),
+        provider: {
+          '@type': 'Organization',
+          name: input.providerName,
+          sameAs: input.providerUrl,
+        },
+      };
+
+    case 'video':
+      return {
+        '@context': 'https://schema.org',
+        '@type': 'VideoObject',
+        name: input.title,
+        description: input.description,
+        url: input.url,
+        ...(input.thumbnailUrl ? { thumbnailUrl: input.thumbnailUrl } : {}),
+        uploadDate: input.uploadDate,
+        ...(input.duration ? { duration: input.duration } : {}),
+      };
+
+    case 'person':
+      return {
+        '@context': 'https://schema.org',
+        '@type': 'Person',
+        name: input.name,
+        url: input.url,
+        ...(input.imageUrl ? { image: input.imageUrl } : {}),
+        ...(input.description ? { description: input.description } : {}),
+        ...(input.jobTitle ? { jobTitle: input.jobTitle } : {}),
+      };
+
+    case 'organization':
+      return {
+        '@context': 'https://schema.org',
+        '@type': 'Organization',
+        name: input.name,
+        url: input.url,
+        ...(input.logoUrl ? { logo: input.logoUrl } : {}),
+        ...(input.description ? { description: input.description } : {}),
+      };
+  }
+}
+
+export function useJsonLd(input: JsonLdInput): void {
+  const jsonLd = buildJsonLd(input);
+
+  useHead({
+    script: [
+      {
+        type: 'application/ld+json',
+        innerHTML: JSON.stringify(jsonLd),
+      },
+    ],
+  });
+}

package/composables/useMarkdownImport.ts

@@ -0,0 +1,77 @@
+/**
+ * Markdown import composable — converts markdown to blocks and handles image uploads.
+ */
+import { markdownToBlockTuples } from '@commonpub/editor';
+import type { BlockTuple } from '@commonpub/editor';
+import type { BlockEditor } from './useBlockEditor';
+
+export function useMarkdownImport(blockEditor: BlockEditor) {
+  const importing = ref(false);
+  const progress = ref({ total: 0, uploaded: 0 });
+
+  async function importMarkdown(md: string, mode: 'append' | 'replace' = 'append'): Promise<void> {
+    importing.value = true;
+    progress.value = { total: 0, uploaded: 0 };
+
+    try {
+      const tuples = markdownToBlockTuples(md);
+      if (!tuples.length) return;
+
+      const editor = blockEditor;
+
+      if (mode === 'replace') {
+        editor.clearBlocks();
+      }
+
+      // Insert blocks sequentially, tracking position for correct ordering
+      let insertAt: number | undefined;
+      if (mode === 'append') {
+        insertAt = editor.blocks.value.length;
+      }
+
+      for (const [type, content] of tuples) {
+        editor.addBlock(type, content as Record<string, unknown>, insertAt);
+        if (insertAt !== undefined) insertAt++;
+      }
+
+      // Find image blocks with remote URLs and upload them
+      const imageBlocks = [...editor.blocks.value].filter(
+        b => b.type === 'image' && b.content.src && isRemoteUrl(b.content.src as string),
+      );
+
+      if (imageBlocks.length > 0) {
+        progress.value.total = imageBlocks.length;
+
+        for (const block of imageBlocks) {
+          try {
+            const result = await $fetch<{ url: string }>('/api/files/upload-from-url', {
+              method: 'POST',
+              body: { url: block.content.src, purpose: 'content' },
+            });
+            editor.updateBlock(block.id, { ...block.content, src: result.url });
+          } catch {
+            // Non-fatal — remote URL stays in place
+            console.warn(`[md-import] Failed to upload image: ${block.content.src}`);
+          }
+          progress.value.uploaded++;
+        }
+      }
+    } finally {
+      importing.value = false;
+    }
+  }
+
+  async function importFile(file: File, mode: 'append' | 'replace' = 'append'): Promise<void> {
+    const text = await file.text();
+    return importMarkdown(text, mode);
+  }
+
+  return { importing, progress, importMarkdown, importFile };
+}
+
+function isRemoteUrl(url: string): boolean {
+  if (!url.startsWith('http')) return false;
+  // Skip URLs that are already on our S3 bucket
+  if (url.includes('digitaloceanspaces.com')) return false;
+  return true;
+}

package/composables/useMirrorContent.ts

@@ -0,0 +1,105 @@
+import type { ContentViewData } from './useEngagement';
+
+/**
+ * Transforms federated content API response into ContentViewData for view components.
+ * Handles block content parsing, metadata extraction, and actor profile mapping.
+ */
+export function useMirrorContent(fedContent: Ref<Record<string, unknown> | null>) {
+  const contentType = computed(() => {
+    const t = (fedContent.value?.cpubType as string) || (fedContent.value?.apType as string)?.toLowerCase() || 'article';
+    return t;
+  });
+
+  const actor = computed(() => fedContent.value?.actor as Record<string, unknown> | null);
+
+  const transformedContent = computed<ContentViewData | null>(() => {
+    const fc = fedContent.value;
+    if (!fc) return null;
+
+    const title = (fc.title as string) || 'Untitled';
+
+    // Parse block content: may be BlockTuple JSON or raw HTML from federation
+    let content: unknown = fc.content;
+    if (typeof content === 'string') {
+      const trimmed = content.trim();
+      if (trimmed.startsWith('[[') || trimmed.startsWith('[["')) {
+        try { content = JSON.parse(trimmed); } catch { /* keep as string */ }
+      }
+      // If still a string (HTML from federation), wrap as BlockTuple array
+      if (typeof content === 'string' && content.trim()) {
+        content = [['paragraph', { html: content }]];
+      }
+    }
+
+    // Extract CommonPub metadata (difficulty, cost, parts) if available
+    const meta = (fc.cpubMetadata as Record<string, unknown>) || null;
+
+    return {
+      id: fc.id as string,
+      type: contentType.value,
+      title,
+      slug: title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, ''),
+      subtitle: null,
+      description: (fc.summary as string) || null,
+      content,
+      coverImageUrl: (fc.coverImageUrl as string) || null,
+      category: null,
+      difficulty: (meta?.difficulty as string) || null,
+      buildTime: (meta?.buildTime as string) || null,
+      estimatedCost: (meta?.estimatedCost as string) || null,
+      status: 'published',
+      visibility: 'public',
+      isFeatured: false,
+      seoDescription: null,
+      previewToken: null,
+      parts: Array.isArray(meta?.parts) ? meta.parts as ContentViewData['parts'] : null,
+      sections: null,
+      viewCount: 0,
+      likeCount: (fc.localLikeCount as number) ?? 0,
+      commentCount: (fc.localCommentCount as number) ?? 0,
+      forkCount: 0,
+      publishedAt: (fc.publishedAt as string) || null,
+      createdAt: (fc.receivedAt as string) || new Date().toISOString(),
+      updatedAt: (fc.receivedAt as string) || new Date().toISOString(),
+      licenseType: null,
+      series: null,
+      estimatedMinutes: null,
+      tags: Array.isArray(fc.tags) ? (fc.tags as Array<{ type: string; name: string }>).map(t => ({ id: '', name: t.name, slug: t.name.toLowerCase().replace(/\s+/g, '-') })) : [],
+      author: {
+        id: '',
+        username: (actor.value?.preferredUsername as string) || 'unknown',
+        displayName: (actor.value?.displayName as string) || (actor.value?.preferredUsername as string) || 'Unknown',
+        avatarUrl: (actor.value?.avatarUrl as string) || null,
+      },
+      buildCount: 0,
+      bookmarkCount: 0,
+    } satisfies ContentViewData;
+  });
+
+  const viewComponent = computed(() => {
+    switch (contentType.value) {
+      case 'article': return resolveComponent('ViewsArticleView');
+      case 'blog': return resolveComponent('ViewsBlogView');
+      case 'explainer': return resolveComponent('ViewsExplainerView');
+      case 'project': return resolveComponent('ViewsProjectView');
+      default: return null;
+    }
+  });
+
+  const originDomain = computed(() => (fedContent.value?.originDomain as string) || 'unknown');
+  const originUrl = computed(() => (fedContent.value?.url as string) || null);
+  const authorHandle = computed(() => {
+    if (!actor.value) return '';
+    return `@${actor.value.preferredUsername ?? 'unknown'}@${actor.value.instanceDomain ?? ''}`;
+  });
+
+  return {
+    contentType,
+    actor,
+    transformedContent,
+    viewComponent,
+    originDomain,
+    originUrl,
+    authorHandle,
+  };
+}