fe-web: improve interfaces for website embedding
- 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