@reallukemanning/folio 1.0.0

package/src/__tests__/benchmarks/ProjectCard.bench.tsx

@@ -0,0 +1,93 @@
+import { bench, describe, beforeAll } from 'vitest'
+import { render } from '@testing-library/react'
+import { ProjectCard } from '../../components/ProjectCard'
+import type { FolioProject } from '../../types'
+
+const createProject = (id: number): FolioProject => ({
+  id: `test-project-${id}`,
+  type: 'github',
+  status: 'active',
+  featured: false,
+  name: `Test Project ${id}`,
+  tagline: `A test project ${id}`,
+  description: `This is a test project description ${id} with some longer text to make it more realistic.`,
+  background: null,
+  why: null,
+  image: null,
+  struggles: [],
+  timeline: [],
+  posts: [],
+  stack: ['React', 'TypeScript', 'Node.js', 'CSS', 'Jest'],
+  links: {
+    github: `https://github.com/test/project-${id}`,
+    live: `https://test-project-${id}.com`,
+    npm: `https://npmjs.com/package/test-${id}`,
+  },
+  stats: {
+    stars: Math.floor(Math.random() * 10000),
+    forks: Math.floor(Math.random() * 1000),
+    downloads: `${Math.floor(Math.random() * 100000)}`,
+    version: '1.0.0',
+  },
+  language: 'TypeScript',
+  languageColor: '#3178c6',
+  createdAt: '2024-01-01',
+  updatedAt: '2024-06-01',
+})
+
+describe('ProjectCard render performance', () => {
+  let projects: FolioProject[]
+
+  beforeAll(() => {
+    projects = Array.from({ length: 100 }, (_, i) => createProject(i))
+  })
+
+  bench('render 100 ProjectCard components', () => {
+    for (const project of projects) {
+      render(
+        <ProjectCard>
+          <ProjectCard.Header project={project} />
+          <ProjectCard.Description project={project} />
+          <ProjectCard.Tags project={project} />
+          <ProjectCard.Stats project={project} />
+          <ProjectCard.Status project={project} />
+          <ProjectCard.Links project={project} />
+        </ProjectCard>
+      )
+    }
+  })
+
+  bench('render single ProjectCard (full composition)', () => {
+    const project = projects[0]
+    render(
+      <ProjectCard>
+        <ProjectCard.Header project={project} />
+        <ProjectCard.Description project={project} />
+        <ProjectCard.Tags project={project} />
+        <ProjectCard.Stats project={project} />
+        <ProjectCard.Status project={project} />
+        <ProjectCard.Links project={project} />
+      </ProjectCard>
+    )
+  })
+
+  bench('render ProjectCard.Header only', () => {
+    const project = projects[0]
+    render(<ProjectCard.Header project={project} />)
+  })
+
+  bench('render ProjectCard.Tags (5 tags)', () => {
+    const project = projects[0]
+    render(<ProjectCard.Tags project={project} />)
+  })
+
+  bench('render ProjectCard.Stats (4 stats)', () => {
+    const project = projects[0]
+    render(<ProjectCard.Stats project={project} />)
+  })
+
+  bench('render ProjectCard.Links (3 links)', () => {
+    const project = projects[0]
+    render(<ProjectCard.Links project={project} />)
+  })
+})

package/src/__tests__/benchmarks/ProjectView.bench.tsx

@@ -0,0 +1,133 @@
+import { bench, describe, beforeAll } from 'vitest'
+import { render } from '@testing-library/react'
+import { ProjectView } from '../../components/ProjectView'
+import type { FolioProject } from '../../types'
+
+const createProject = (id: number): FolioProject => ({
+  id: `test-project-${id}`,
+  type: 'github',
+  status: 'active',
+  featured: false,
+  name: `Test Project ${id}`,
+  tagline: `A test project ${id}`,
+  description: `This is a test project description ${id} with some longer text to make it more realistic.`,
+  background: `This is the background story for project ${id}. It explains the motivation and context.`,
+  why: `Why this project matters ${id}.`,
+  image: null,
+  struggles: [
+    { type: 'warn', text: 'First challenge faced' },
+    { type: 'error', text: 'Major obstacle encountered' },
+  ],
+  timeline: [
+    { date: '2024-01', note: 'Project started' },
+    { date: '2024-03', note: 'MVP completed' },
+    { date: '2024-06', note: 'Public launch' },
+  ],
+  posts: [
+    { title: 'Launch announcement', date: '2024-06-01', url: 'https://blog.example.com/launch' },
+    { title: 'Technical deep dive', date: '2024-07-15' },
+  ],
+  stack: ['React', 'TypeScript', 'Node.js', 'CSS', 'Jest'],
+  links: {
+    github: `https://github.com/test/project-${id}`,
+    live: `https://test-project-${id}.com`,
+    npm: `https://npmjs.com/package/test-${id}`,
+  },
+  stats: {
+    stars: Math.floor(Math.random() * 10000),
+    forks: Math.floor(Math.random() * 1000),
+    downloads: `${Math.floor(Math.random() * 100000)}`,
+    version: '1.0.0',
+  },
+  language: 'TypeScript',
+  languageColor: '#3178c6',
+  createdAt: '2024-01-01',
+  updatedAt: '2024-06-01',
+})
+
+describe('ProjectView render performance', () => {
+  let projects: FolioProject[]
+
+  beforeAll(() => {
+    projects = Array.from({ length: 100 }, (_, i) => createProject(i))
+  })
+
+  bench('render 100 ProjectView components', () => {
+    for (const project of projects) {
+      render(
+        <ProjectView project={project} onBack={() => {}}>
+          <ProjectView.Section project={project} name="background" />
+          <ProjectView.Section project={project} name="why" />
+          <ProjectView.Section project={project} name="stack" />
+          <ProjectView.Section project={project} name="struggles" />
+          <ProjectView.Section project={project} name="timeline" />
+          <ProjectView.Section project={project} name="posts" />
+          <ProjectView.Stats project={project} />
+          <ProjectView.Links project={project} />
+        </ProjectView>
+      )
+    }
+  })
+
+  bench('render single ProjectView (full composition)', () => {
+    const project = projects[0]
+    render(
+      <ProjectView project={project} onBack={() => {}}>
+        <ProjectView.Section project={project} name="background" />
+        <ProjectView.Section project={project} name="why" />
+        <ProjectView.Section project={project} name="stack" />
+        <ProjectView.Section project={project} name="struggles" />
+        <ProjectView.Section project={project} name="timeline" />
+        <ProjectView.Section project={project} name="posts" />
+        <ProjectView.Stats project={project} />
+        <ProjectView.Links project={project} />
+      </ProjectView>
+    )
+  })
+
+  bench('render ProjectView (no onBack)', () => {
+    const project = projects[0]
+    render(
+      <ProjectView project={project}>
+        <ProjectView.Section project={project} name="background" />
+        <ProjectView.Stats project={project} />
+        <ProjectView.Links project={project} />
+      </ProjectView>
+    )
+  })
+
+  bench('render ProjectView.Section (string content)', () => {
+    const project = projects[0]
+    render(<ProjectView.Section project={project} name="background" />)
+  })
+
+  bench('render ProjectView.Section (array - stack)', () => {
+    const project = projects[0]
+    render(<ProjectView.Section project={project} name="stack" />)
+  })
+
+  bench('render ProjectView.Section (array - struggles)', () => {
+    const project = projects[0]
+    render(<ProjectView.Section project={project} name="struggles" />)
+  })
+
+  bench('render ProjectView.Section (array - timeline)', () => {
+    const project = projects[0]
+    render(<ProjectView.Section project={project} name="timeline" />)
+  })
+
+  bench('render ProjectView.Section (array - posts)', () => {
+    const project = projects[0]
+    render(<ProjectView.Section project={project} name="posts" />)
+  })
+
+  bench('render ProjectView.Stats', () => {
+    const project = projects[0]
+    render(<ProjectView.Stats project={project} />)
+  })
+
+  bench('render ProjectView.Links', () => {
+    const project = projects[0]
+    render(<ProjectView.Links project={project} />)
+  })
+})

package/src/__tests__/benchmarks/github.bench.ts

@@ -0,0 +1,53 @@
+import { bench, describe, beforeAll, vi } from 'vitest'
+
+const mockGitHubResponse = {
+  name: 'folio',
+  description: 'A component library for project showcases',
+  stargazers_count: 1234,
+  forks_count: 56,
+  language: 'TypeScript',
+  topics: ['react', 'typescript', 'portfolio', 'components'],
+  html_url: 'https://github.com/test/folio',
+  homepage: 'https://folio.dev',
+  created_at: '2024-01-01T00:00:00Z',
+  updated_at: '2024-06-01T00:00:00Z',
+}
+
+describe('fetchGitHubRepo performance', () => {
+  beforeAll(() => {
+    vi.stubGlobal('fetch', vi.fn(async () => ({
+      ok: true,
+      json: async () => mockGitHubResponse,
+    })))
+  })
+
+  bench('fetchGitHubRepo with cache (build strategy simulation)', async () => {
+    const response = await fetch('https://api.github.com/repos/test/folio', {
+      cache: 'force-cache',
+    })
+    await response.json()
+  })
+
+  bench('fetchGitHubRepo without cache (runtime strategy simulation)', async () => {
+    const response = await fetch('https://api.github.com/repos/test/folio', {
+      cache: 'no-store',
+    })
+    await response.json()
+  })
+
+  bench('parse GitHub API response', () => {
+    const data = mockGitHubResponse
+    void {
+      name: data.name,
+      description: data.description,
+      stargazers_count: data.stargazers_count,
+      forks_count: data.forks_count,
+      language: data.language,
+      topics: data.topics || [],
+      html_url: data.html_url,
+      homepage: data.homepage,
+      created_at: data.created_at,
+      updated_at: data.updated_at,
+    }
+  })
+})

package/src/__tests__/benchmarks/npm.bench.ts

@@ -0,0 +1,62 @@
+import { bench, describe, beforeAll, vi } from 'vitest'
+
+const mockDownloadsResponse = {
+  package: 'folio-core',
+  downloads: 123456,
+}
+
+const mockRegistryResponse = {
+  name: 'folio-core',
+  'dist-tags': {
+    latest: '1.2.3',
+  },
+  versions: {
+    '1.2.3': {
+      version: '1.2.3',
+    },
+  },
+}
+
+describe('fetchNpmPackage performance', () => {
+  beforeAll(() => {
+    vi.stubGlobal('fetch', vi.fn(async (url: string) => {
+      if (url.includes('downloads')) {
+        return {
+          ok: true,
+          json: async () => mockDownloadsResponse,
+        }
+      }
+      return {
+        ok: true,
+        json: async () => mockRegistryResponse,
+      }
+    }))
+  })
+
+  bench('fetchNpmPackage (parallel fetch simulation)', async () => {
+    const [downloadsResponse, registryResponse] = await Promise.all([
+      fetch('https://api.npmjs.org/downloads/point/last-month/folio-core', {
+        cache: 'force-cache',
+      }),
+      fetch('https://registry.npmjs.org/folio-core', {
+        cache: 'force-cache',
+      }),
+    ])
+
+    const downloadsData = await downloadsResponse.json()
+    const registryData = await registryResponse.json()
+
+    void registryData['dist-tags']?.latest
+    void downloadsData.package
+    void downloadsData.downloads
+  })
+
+  bench('parse npm API responses', () => {
+    const downloadsData = mockDownloadsResponse
+    const registryData = mockRegistryResponse
+
+    void registryData['dist-tags']?.latest
+    void downloadsData.package
+    void downloadsData.downloads
+  })
+})

package/src/__tests__/benchmarks/product-hunt.bench.ts

@@ -0,0 +1,58 @@
+import { bench, describe, beforeAll, vi } from 'vitest'
+
+const mockProductHuntResponse = {
+  post: {
+    name: 'Folio',
+    tagline: 'Beautiful project showcases',
+    description: 'A component library for developers and solopreneurs building project showcase pages.',
+    votes_count: 456,
+    comments_count: 78,
+    featured_at: '2024-06-01T00:00:00Z',
+    website: 'https://folio.dev',
+    url: 'https://producthunt.com/posts/folio',
+  },
+}
+
+describe('fetchProductHuntPost performance', () => {
+  beforeAll(() => {
+    vi.stubGlobal('fetch', vi.fn(async () => ({
+      ok: true,
+      json: async () => mockProductHuntResponse,
+    })))
+  })
+
+  bench('fetchProductHuntPost (authenticated)', async () => {
+    const response = await fetch('https://api.producthunt.com/v2/posts/folio', {
+      headers: {
+        Authorization: 'Bearer test-token',
+        Accept: 'application/json',
+      },
+      cache: 'force-cache',
+    })
+    const data = await response.json()
+    const post = data.post
+
+    void post.name
+    void post.tagline
+    void post.description
+    void post.votes_count
+    void post.comments_count
+    void post.featured_at
+    void post.website
+    void post.url
+  })
+
+  bench('parse Product Hunt API response', () => {
+    const data = mockProductHuntResponse
+    const post = data.post
+
+    void post.name
+    void post.tagline
+    void post.description
+    void post.votes_count
+    void post.comments_count
+    void post.featured_at
+    void post.website
+    void post.url
+  })
+})

package/src/__tests__/benchmarks/utilities.bench.ts

@@ -0,0 +1,131 @@
+import { bench, describe, beforeAll } from 'vitest'
+import { filterByType } from '../../lib/filterByType'
+import { filterByStatus } from '../../lib/filterByStatus'
+import { filterByFeatured } from '../../lib/filterByFeatured'
+import { sortByName } from '../../lib/sortByName'
+import { sortByDate } from '../../lib/sortByDate'
+import { sortByStars } from '../../lib/sortByStars'
+import type { FolioProject, ProjectStatus, ProjectType } from '../../types'
+
+const createProject = (id: number): FolioProject => ({
+  id: `project-${id}`,
+  type: (['github', 'npm', 'product-hunt', 'manual', 'hybrid'] as ProjectType[])[id % 5],
+  status: (['active', 'shipped', 'in-progress', 'archived'] as ProjectStatus[])[id % 4],
+  featured: id % 10 === 0,
+  name: `Project ${String(id).padStart(4, '0')}`,
+  tagline: `A test project ${id}`,
+  description: `Description for project ${id}`,
+  background: null,
+  why: null,
+  image: null,
+  struggles: [],
+  timeline: [],
+  posts: [],
+  stack: ['React', 'TypeScript', 'Node.js'],
+  links: {
+    github: `https://github.com/test/project-${id}`,
+    live: `https://project-${id}.com`,
+  },
+  stats: {
+    stars: Math.floor(Math.random() * 10000),
+    forks: Math.floor(Math.random() * 1000),
+  },
+  language: 'TypeScript',
+  languageColor: '#3178c6',
+  createdAt: new Date(2024, id % 12, (id % 28) + 1).toISOString(),
+  updatedAt: new Date(2024, (id % 12) + 1, 1).toISOString(),
+})
+
+describe('Utility functions performance (1000 projects)', () => {
+  let projects: FolioProject[]
+
+  beforeAll(() => {
+    projects = Array.from({ length: 1000 }, (_, i) => createProject(i))
+  })
+
+  describe('filterByType', () => {
+    bench('filter by github', () => {
+      filterByType(projects, 'github')
+    })
+
+    bench('filter by npm', () => {
+      filterByType(projects, 'npm')
+    })
+
+    bench('filter by all (no-op)', () => {
+      filterByType(projects, 'all')
+    })
+
+    bench('filter by undefined (no-op)', () => {
+      filterByType(projects, undefined)
+    })
+  })
+
+  describe('filterByStatus', () => {
+    bench('filter by active', () => {
+      filterByStatus(projects, 'active')
+    })
+
+    bench('filter by shipped', () => {
+      filterByStatus(projects, 'shipped')
+    })
+  })
+
+  describe('filterByFeatured', () => {
+    bench('filter featured projects', () => {
+      filterByFeatured(projects, true)
+    })
+
+    bench('filter non-featured projects', () => {
+      filterByFeatured(projects, false)
+    })
+  })
+
+  describe('sortByName', () => {
+    bench('sort by name ascending', () => {
+      sortByName(projects, 'asc')
+    })
+
+    bench('sort by name descending', () => {
+      sortByName(projects, 'desc')
+    })
+  })
+
+  describe('sortByDate', () => {
+    bench('sort by date ascending', () => {
+      sortByDate(projects, 'asc')
+    })
+
+    bench('sort by date descending', () => {
+      sortByDate(projects, 'desc')
+    })
+  })
+
+  describe('sortByStars', () => {
+    bench('sort by stars ascending', () => {
+      sortByStars(projects, 'asc')
+    })
+
+    bench('sort by stars descending', () => {
+      sortByStars(projects, 'desc')
+    })
+  })
+
+  describe('combined operations', () => {
+    bench('filter by github then sort by stars', () => {
+      const filtered = filterByType(projects, 'github')
+      sortByStars(filtered, 'desc')
+    })
+
+    bench('filter featured then sort by date', () => {
+      const featured = filterByFeatured(projects, true)
+      sortByDate(featured, 'desc')
+    })
+
+    bench('filter by status then by type then sort', () => {
+      const active = filterByStatus(projects, 'active')
+      const github = filterByType(active, 'github')
+      sortByStars(github, 'desc')
+    })
+  })
+})

package/src/cli-components/FeaturedProject/FeaturedProject.tsx

@@ -0,0 +1,54 @@
+import type { FolioProject } from '../types.js'
+
+function FeaturedProject({ project }: { project: FolioProject | null | undefined }) {
+  if (!project) {
+    return null
+  }
+
+  return (
+    <div data-folio-featured>
+      {project.image && <img data-folio-featured-image src={project.image} alt={project.name} />}
+      <div data-folio-view>
+        <h2>{project.name}</h2>
+        {project.background && <div data-folio-view-section data-folio-view-section-name="background">{project.background}</div>}
+        {project.why && <div data-folio-view-section data-folio-view-section-name="why">{project.why}</div>}
+        {project.stats && (project.stats.stars || project.stats.forks || project.stats.downloads) && (
+          <div data-folio-card-stats>
+            {project.stats.stars && <span data-folio-stat="stars">{project.stats.stars} stars</span>}
+            {project.stats.forks && <span data-folio-stat="forks">{project.stats.forks} forks</span>}
+            {project.stats.downloads && <span data-folio-stat="downloads">{project.stats.downloads} downloads</span>}
+          </div>
+        )}
+        <div data-folio-view-links>
+          {project.links.github && (
+            <a href={project.links.github} data-folio-link data-folio-link-type="github">
+              GitHub
+            </a>
+          )}
+          {project.links.live && (
+            <a href={project.links.live} data-folio-link data-folio-link-type="live">
+              Live
+            </a>
+          )}
+          {project.links.npm && (
+            <a href={project.links.npm} data-folio-link data-folio-link-type="npm">
+              npm
+            </a>
+          )}
+          {project.links.appStore && (
+            <a href={project.links.appStore} data-folio-link data-folio-link-type="app-store">
+              App Store
+            </a>
+          )}
+          {project.links.playStore && (
+            <a href={project.links.playStore} data-folio-link data-folio-link-type="play-store">
+              Play Store
+            </a>
+          )}
+        </div>
+      </div>
+    </div>
+  )
+}
+
+export { FeaturedProject }

package/src/cli-components/FeaturedProject/index.ts

@@ -0,0 +1,2 @@
+export { FeaturedProject } from './FeaturedProject.js'
+export type { FolioProject } from '../types.js'

package/src/cli-components/ProjectCard/ProjectCard.tsx

@@ -0,0 +1,90 @@
+import type { FolioProject } from '../types.js'
+
+function ProjectCard({ children }: { children: React.ReactNode }) {
+  return <div data-folio-card>{children}</div>
+}
+
+ProjectCard.Header = function ProjectCardHeader({ project }: { project: FolioProject }) {
+  return (
+    <div data-folio-card-header>
+      <h3>{project.name}</h3>
+      <div data-folio-type data-folio-type-value={project.type}>
+        {project.type}
+      </div>
+    </div>
+  )
+}
+
+ProjectCard.Description = function ProjectCardDescription({ project }: { project: FolioProject }) {
+  if (!project.description) return null
+  return <div data-folio-card-description>{project.description}</div>
+}
+
+ProjectCard.Tags = function ProjectCardTags({ project }: { project: FolioProject }) {
+  if (!project.stack || project.stack.length === 0) return null
+  return (
+    <div data-folio-card-tags>
+      {project.stack.map((tag) => (
+        <span key={tag} data-folio-tag>
+          {tag}
+        </span>
+      ))}
+    </div>
+  )
+}
+
+ProjectCard.Stats = function ProjectCardStats({ project }: { project: FolioProject }) {
+  if (!project.stats || (!project.stats.stars && !project.stats.forks && !project.stats.downloads && !project.stats.version && !project.stats.upvotes && !project.stats.comments)) {
+    return null
+  }
+  return (
+    <div data-folio-card-stats>
+      {project.stats.stars && <span data-folio-stat="stars">{project.stats.stars} stars</span>}
+      {project.stats.forks && <span data-folio-stat="forks">{project.stats.forks} forks</span>}
+      {project.stats.downloads && (
+        <span data-folio-stat="downloads">{project.stats.downloads} downloads</span>
+      )}
+      {project.stats.version && <span data-folio-stat="version">{project.stats.version}</span>}
+      {project.stats.upvotes && <span data-folio-stat="upvotes">{project.stats.upvotes} upvotes</span>}
+      {project.stats.comments && <span data-folio-stat="comments">{project.stats.comments} comments</span>}
+    </div>
+  )
+}
+
+ProjectCard.Status = function ProjectCardStatus({ project }: { project: FolioProject }) {
+  return (
+    <div data-folio-status data-folio-status-value={project.status}>
+      {project.status}
+    </div>
+  )
+}
+
+ProjectCard.Links = function ProjectCardLinks({ project }: { project: FolioProject }) {
+  if (!project.links.github && !project.links.live && !project.links.npm && !project.links.productHunt) return null
+  return (
+    <div data-folio-card-links>
+      {project.links.github && (
+        <a href={project.links.github} data-folio-link data-folio-link-type="github">
+          GitHub
+        </a>
+      )}
+      {project.links.live && (
+        <a href={project.links.live} data-folio-link data-folio-link-type="live">
+          Live
+        </a>
+      )}
+      {project.links.npm && (
+        <a href={project.links.npm} data-folio-link data-folio-link-type="npm">
+          npm
+        </a>
+      )}
+      {project.links.productHunt && (
+        <a href={project.links.productHunt} data-folio-link data-folio-link-type="product-hunt">
+          Product Hunt
+        </a>
+      )}
+    </div>
+  )
+}
+
+export { ProjectCard }

package/src/cli-components/ProjectCard/index.ts

@@ -0,0 +1,2 @@
+export { ProjectCard } from './ProjectCard.js'
+export type { FolioProject } from '../types.js'

package/src/cli-components/ProjectGrid/ProjectGrid.tsx

@@ -0,0 +1,6 @@
+function ProjectGrid({ children }: { children: React.ReactNode }) {
+  if (!children) return null
+  return <div data-folio-grid>{children}</div>
+}
+
+export { ProjectGrid }