argotorg / argotorg/fe

fe-web: improve interfaces for website embedding

Open
#1,375 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Rust
Stars
1.7k
Forks
218
Avg merge
1d 4h
Merged PRs (30d)
8

Description

## Context

While integrating the fe doc viewer and `` into the Astro/Starlight website ([www PR #8](https://github.com/fe-lang/www/pull/8)), we hit several interface gaps that required workarounds. This issue tracks the changes needed to make embedding clean.

## Current Pain Points

### 1. Shadow DOM stylesheet resolution
`_getCodeBlockSheet()` in `fe-code-block.js` only scans `` tags for highlight CSS. A `<link rel="stylesheet">` (the standard web approach) doesn't work. Host sites have to inline the CSS via raw imports.

### 2. Click navigation hardcodes `location.hash`
`fe-code-block.js` line 426 does `location.hash = "#" + docPath`. Doesn't check `FE_DOCS_BASE`. Breaks when embedded on a page that isn't the SPA viewer (pollutes URL, breaks back button). Required a hashchange listener with replaceState workaround.

### 3. Global namespace pollution
`window.FE_SCIP`, `window.FE_DOCS_BASE`, `window.FE_DOC_INDEX`, `window.feHighlight`, `window.feUnhighlight`, `window.FeHighlighter`, etc. The bundle can't be loaded as `type="module"` because these functions need to be global for the custom elements to find them.

### 4. Monolithic static output
`fe doc static` produces a single 5.7MB HTML file with everything inlined (styles, SCIP data, doc data, JS). Can't override theme via CSS cascade. Can't add custom head elements. Can't serve individual assets from CDN.

### 5. No navigation control for embedded code blocks
When `<fe-code-block>` is on a page outside the doc viewer, all symbol clicks navigate unconditionally. No way to filter (e.g., "only link stdlib types, not local definitions") or intercept (e.g., "open in new tab" or "show popover").

### 6. Empty SCIP file key
`fe doc json` on a single file produces `""` as the file path key in `scip.files`.

## Proposed Changes (prioritized)

### P0: Fix shadow DOM stylesheet resolution
Support `<link>` stylesheets in `_getCodeBlockSheet()`, not just inline `<style>` tags. Check `document.styleSheets` for linked stylesheets containing the highlight rules.

### P0: Navigation via CustomEvent
Before mutating `location`, dispatch a cancellable `CustomEvent("fe-navigate", { detail: { symbol, docPath } })`. Host pages can `preventDefault()` to handle navigation themselves. Fall back to current behavior if not cancelled. This replaces both the `FE_DOCS_BASE` check AND the link filtering need.

### P1: Proper module exports
Assign globals explicitly (`window.feHighlight = feHighlight`) in the bundle so `type="module"` works. Long-term, move toward attribute/property-based configuration on the custom elements rather than globals.

### P1: Split static output
`fe doc static` should output separate files (index.html shell, fe-web.js, fe-highlight.css, docs.json) that can be composed with normal web tooling. The monolithic mode could remain as a `--self-contained` flag.

### P2: Fix empty SCIP file key
Use the filename when the relative path would be empty.

### P2: Configuration via element attributes
Move toward `<fe-code-block src="..." base="...">` instead of global `window.FE_DOCS_BASE`. The custom element discovers its own configuration.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with fe-code-block.js, especially _getCodeBlockSheet() and the navigation at line 426, then inspect the fe doc json and fe doc static entry points. The issue spans stylesheet lookup, navigation events, module exports, static output, and SCIP paths; done means the prioritized embedding gaps are addressed without the current host-page workarounds.

Written by the indexing model from the issue text.

Assessment

Tech stack
css, html, javascript
Domain
documentation, frontend, web-dev
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.