docs: add Styling guide (adopted style sheets, css helper, CSS modules) - #182
Open
megheaiulian wants to merge 2 commits into
Open
megheaiulian wants to merge 2 commits into
megheaiulian wants to merge 2 commits into
Conversation
- New guides/styling page covering inline <style>, the styleSheets
option, the css tagged template (with interpolation/composition
for theming), renderer-level styleSheets precedence, the sheet()
helper, and native CSS modules (import ... with { type: 'css' })
which work out of the box since styleSheets accepts existing
CSSStyleSheet instances
- Documents light DOM behavior: styleSheets requires a shadow root
to adopt into, with document.adoptedStyleSheets alternative
- Includes API reference table for css, sheet, styleSheets,
shadowRootInit and useShadowDOM options
- Add Styling card to guides index and sidebar entry in
astro.config.mjs; remap the guides index card icons to valid
Starlight built-in names while there
- Fix README component() Options signature: add shadowRootInit and
styleSheets, which were missing entirely
Starlight silently skips unknown icon names (Icons[name] -> undefined), so every Card on the hooks index rendered icon-less: they were authored with non-existent names (repeat, share, sync, settings, speed, memory, layers, filter-list, bookmark). Remap all hook cards to semantically-close built-in icons: useCallback -> link, useContext -> external, useEffect -> analytics, useHost -> setting, useLayoutEffect -> clock, useMemo -> database, useProperty -> pen, useReducer -> list-format, useRef -> magnifier. Verified post-build: all 10 hook cards now render <svg> icons.
|
✅ Deploy Preview for pionjs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a long-requested Styling guide and fixes two doc-site defects found along the way.
New:
guides/stylingpageCovers the styling APIs that have zero documentation today despite heavy real-world use (123+
cssimports across Neovici's cosmoz components;styleSheetsused by nearly every modern component):<style>in templates — when it's fine, when it's notstyleSheetsoption + thecsstagged template, with the*.style.tsfile convention used in the wild as the recommended patterncssinterpolationApp.styleSheetsand its precedence over optionssheet()helper for standaloneCSSStyleSheetconstructionimport styles from './my-app.css' with { type: 'css' }works out of the box sincestyleSheetspasses through existingCSSStyleSheetinstances; includes bundler notesstyleSheetsrequires a shadow root to adopt into, with thedocument.adoptedStyleSheetsalternativecss,sheet,styleSheets,shadowRootInit,useShadowDOMAlso wires the page into the sidebar and guides index, and fixes the README
component()Optionssignature, which was missingshadowRootInitandstyleSheetsentirely.Fixed: silently-broken card icons
Starlight silently skips unknown icon names (
Icons[name]→undefined), so all 23 cards across the guides index, hooks index and homepage rendered without icons — they were authored with names that don't exist in Starlight's built-in set (settings,layers,terminal,view-in-ar,repeat,memory,bookmark, …).Remapped all cards to semantically-close built-in icons (e.g. Attributes →
setting, useLayoutEffect →clock, useMemo →database). Verified post-build: all 9/10/4 cards now render<svg>icons.Verification
npm run buildindocs/— 23 pages, zero warningsicon="…"in the repo validated against Starlight's actual icon setNotes for review
src/component.tsL98–121 forstyleSheets/shadowRootInit/useShadowDOM;src/util.tsforcss/sheet) and cross-checked against production usage patterns across the cosmoz-* component family