Repository Home Components

Purpose and Scope

The repository home experience is the entry point that turns a GitHub repository into an OpenWiki wiki. It covers the public landing page where a user can paste a repository URL, the repository route that decides whether a wiki already exists, the client-side auto-indexing state for unknown repositories, and the progress card shown while the indexing job runs. These components are presentation code, but they also encode important product behavior: when to search, when to start generation, how to handle disabled creation, how to display rate limits, and how to refresh the route after a wiki is published.

Sources: app/components/repository-home.tsx, app/repos/[owner]/[repo]/repository-wiki-page.tsx

The main user problem is uncertainty. A visitor may arrive with a full GitHub URL, a partial repository name, or a direct route such as an owner and repo pair. The UI needs to guide each path without forcing the user to understand the indexing engine. The home component accepts featured repository metadata, lets the browser query search and featured endpoints, and navigates users to canonical repository routes. The repository wiki page then becomes the handoff point: it either renders an existing wiki, shows an operational error state, or starts generation for an empty repository shell.

Sources: app/components/repository-home.tsx, app/repos/[owner]/[repo]/repository-wiki-page.tsx

Relevant Source Files

• app/components/repository-home.tsx: Client component for the root repository picker, featured repository cards, debounced repository search, query-parameter hydration, and navigation into repository wiki routes.
• app/components/repository-auto-index.tsx: Client component that starts wiki generation for an unindexed repository by posting to the repository API, tracks retry state, and translates rate-limit or disabled-creation responses into user-facing states.
• app/components/index-job-progress.tsx: Shared progress component that polls indexing job status, maps internal phases into readable labels, refreshes the route after completion, and renders the generic wiki-generation state card.
• app/lib/format-indexed-at.ts: Formatting helper for compact relative timestamps such as seconds, minutes, hours, and days, with a date fallback for older wiki revisions.
• app/repos/[owner]/[repo]/repository-wiki-page.tsx: Server component for repository wiki rendering, empty-wiki auto-index handoff, disabled-creation state, wiki navigation, copy markdown affordance, and embedded repository chat.

Core UI Primitives

The component set has three practical primitives. First, repository discovery lives in the home form. The user input is stored as a string, trimmed, and interpreted by the GitHub URL parser. If the text is already a valid repository URL, submission can navigate directly. If the text is at least two characters but not a parseable URL, it becomes a search query. This distinction keeps paste-driven creation fast while still supporting discovery-style typing, and it prevents search calls from firing for complete repository URLs that should be routed instead.

Sources: app/components/repository-home.tsx

Second, auto-indexing is modeled as an idempotent client-side starter. The auto-index component keeps a ref containing the repository URL it has already attempted, so a visible page does not repeatedly submit the same creation request. It also listens to document visibility and waits until the page is visible before starting work. That detail matters for user experience and cost control because a background tab should not eagerly trigger a generation job that the user may never watch, especially on public deployments with rate limits.

Sources: app/components/repository-auto-index.tsx

Third, progress display is separated from job creation. Once a job identifier exists, the progress component polls the indexing-job API every two seconds with no-store caching. It maintains the last job payload, transient polling errors, and an error counter. The visible label is derived from the job status and phase, not from the creation component. This separation lets the same progress renderer be reused from search parameters or from the auto-index workflow, while giving completed jobs a consistent route cleanup through replace and refresh.

Sources: app/components/index-job-progress.tsx

Repository Home Flow

The root home component starts from server-provided featured repositories but refreshes their metadata on the client through the featured repository API with cache disabled. That means a prerendered or initially loaded page can show useful cards immediately, then improve star counts, descriptions, or icons after hydration. The request is protected with an AbortController so the component does not update state after unmount. For a landing page that may be visited briefly before navigation, that cleanup keeps the UI predictable and avoids stale async updates.

Sources: app/components/repository-home.tsx

Search uses a deliberate debounce. When the trimmed input is shorter than two characters, or when the parser recognizes it as a GitHub repository URL, results are cleared and the status returns to idle. Otherwise, a timer waits before calling the repository search endpoint with an encoded query. Successful responses populate repository results and switch the status to success; failures switch to error and produce a clear message. The user sees either search results, a no-results state, or a failure state based on the same state machine, instead of receiving unrelated validation messages.

Sources: app/components/repository-home.tsx

The home page also synchronizes the input from the URL query string. On mount and when search parameters change, the component reads the q parameter into local state. This supports shareable or prefilled searches and lets other navigation paths send a user back to the home page with context. The same component imports the repository URL helpers used elsewhere, so repository labels and hrefs are not reinvented in the UI. The result is a landing page that treats direct repository creation and discovery as two views of the same repository-routing problem.

Sources: app/components/repository-home.tsx

Empty Repository and Auto-Index States

The repository wiki page is the server-side decision point for a repository route. It asks storage for the wiki by owner, repository name, and optional slug. Storage configuration failures and unavailable artifacts are handled as specific states, while a missing wiki for a slug becomes a not-found response. If no wiki exists for the repository root, the page creates an empty repository model and renders a centered generation state inside the normal OpenWiki shell. This gives direct repository URLs the same polished experience as repositories selected from the home page.

Sources: app/repos/[owner]/[repo]/repository-wiki-page.tsx

When the repository has no pages, the route checks whether repository creation is disabled. If creation is disabled, it renders a disabled state instead of starting background work. If creation is allowed, it renders the auto-index component with the full repository label and GitHub URL. The auto-index component posts JSON to the repository API and expects either a job, no job, or an error code. A missing job is treated as a signal that the route can refresh, which covers cases where another request already produced a wiki or the backend decided no new job was required.

Sources: app/components/repository-auto-index.tsx, app/repos/[owner]/[repo]/repository-wiki-page.tsx

Two explicit error codes shape the user-facing behavior. A repository generation rate-limit response shows a muted state explaining that generation is rate limited. A repository creation disabled response shows a separate message explaining that creation is disabled for the deployment. Any other failed response becomes a general start error. The component also exposes a restart callback that clears the started URL, messages, current job, and increments an attempt counter. That callback is important when the progress API tells the UI that the current job should be restarted.

Sources: app/components/repository-auto-index.tsx, app/components/index-job-progress.tsx

Progress Labels and Refresh Behavior

Indexing progress is intentionally phrased in product language rather than raw backend terminology. The progress component maps phases such as reading repository content, preparing source context, planning the wiki structure, generating pages, publishing, and revalidating into human-readable labels. The labels set expectations about duration, including the outline phase being described as taking a couple minutes. If a phase is unknown, the component falls back to displaying the raw phase, which keeps future backend phases visible even before the UI has been updated.

Sources: app/components/index-job-progress.tsx

The polling loop distinguishes backend job failure from temporary progress unavailability. A failed job displays the job error message. Polling errors increment an error counter, and only persistent failures become a visible unavailable state. That avoids alarming users on a single transient network issue while still surfacing real inability to read progress. When the job reports completion, the component removes the job query context from the URL and refreshes the route. The refreshed route can then render the newly published wiki through the server component rather than leaving the user on a stale progress card.

Sources: app/components/index-job-progress.tsx, app/repos/[owner]/[repo]/repository-wiki-page.tsx

Rendered Wiki Presentation Helpers

Once a wiki exists, the repository page switches from generation mode to wiki mode. It builds navbar metadata with the active wiki mode, chat href, current wiki href, repository icon source, label, and root wiki href. It also computes the active slug, current page href, table of contents, and root repository route. The rendered page includes mobile wiki navigation, a persistent scroll area, markdown rendering, copy markdown behavior, and repository chat integration. These details make the repository page both a document reader and a launch point for asking questions about the indexed source.

Sources: app/repos/[owner]/[repo]/repository-wiki-page.tsx

The timestamp helper supports this presentation by converting an indexed time into compact relative text. Recent indexes are formatted as seconds ago, then minutes, hours, and days. After a week, the helper switches to a localized English date and omits the year when the date is in the current year. This keeps repository metadata readable in dense navigation or header areas. It also avoids misleading negative values by clamping elapsed seconds to zero before choosing the display unit.

Sources: app/lib/format-indexed-at.ts

Component Reference

Component or helper	Role	Key behavior
RepositoryHome	Landing-page repository picker	Hydrates input from q, refreshes featured repositories, searches non-URL queries, and routes valid repositories.
RepositoryAutoIndex	Empty-repository generation starter	Posts repoUrl to the repository API, handles creation-disabled and rate-limit codes, stores job state, and supports restart.
IndexJobProgress	Indexing progress renderer	Polls job status, maps phases to labels, handles persistent polling errors, refreshes after completion.
IndexJobProgressFromSearchParams	Query-string adapter	Reads a job parameter and renders progress when present.
WikiGenerationState	Shared status card	Displays loading, muted, default, or destructive generation states with repository context.
formatIndexedAt	Timestamp formatter	Produces compact relative labels and a localized date fallback.
RepositoryWikiPage	Server route renderer	Fetches stored wiki data, handles storage and artifact states, starts auto-indexing for empty wikis, and renders wiki navigation.

Next Steps

When changing the repository home experience, keep the boundary between discovery, job creation, and progress rendering intact. Discovery should stay in the home component, generation start logic should remain idempotent in the auto-index component, and job status polling should remain reusable. For routing or storage changes, review the repository API and indexing job API pages next, because these components depend on the response shapes and error codes exposed by those routes. For reader-facing wiki changes, continue with the navigation and layout components page, which covers the shell pieces surrounding the repository page.