svelte-css.ts

internal

A Svelte component's styling API: the CSS custom properties its styles read with a fallback, or register with @property, and leave for a consumer to set (ComponentDeclarationJson.cssCustomProperties).

Svelte's own parser reads the component, with script content blanked, so the stylesheet and the markup come from one parse: ast.css gives the declarations and @property rules, and the template gives the style:--x directives and style attributes that set properties internally, plus the static style text the markup reads through. Declaration values are scanned from the original source text (scanCssVarReads), since the parser strips comments from them and gives no offsets inside them.

@cssprop tags in the component's doc comment merge in afterwards (documentCssProperties), checked against every read the component makes and against the fallback the style gives.

view source

Declarations
#

9 declarations

analyzeComponentCss
#

svelte-css.ts view source

(svelteSource: string): ComponentCss import {analyzeComponentCss} from 'svelte-docinfo/svelte-css.js';

Read a component's styling API: the custom properties its top-level <style> and its markup's static style text read through an outermost var() with a fallback, or that its style registers with @property, minus the ones it sets itself. The policy is ComponentDeclarationJson.cssCustomProperties's.

One parse with Svelte's parser (modern, loose) over the source with its script content blanked, so script syntax never fails it. A style whose lang or type names another language is blanked too, and reported as css_lang_unsupported. A parse failure reports css_parse_failed, with the parser's position. A source without <style text is parsed only when its non-script text has var(, for its markup's reads; otherwise it reads nothing, with empty reads. Every read, the ones it doesn't list included, lands in reads for documentCssProperties.

svelteSource

the full Svelte source code

type string

returns

ComponentCss

the styling API, plus the problem when the style wasn't read

ComponentCss
#

svelte-css.ts view source

ComponentCss import type {ComponentCss} from 'svelte-docinfo/svelte-css.js';

What analyzeComponentCss reads from a component.

properties

The styling API, in the order of each name's first read.

type ComponentCssPropertyJsonInput[]

reads?

Every custom property the component reads through var(), by name: in its <style> at any nesting (var(--a, var(--b)) reads both), and in the static text of its markup's style attributes, style: directives, and child components' style and --a attributes. Names the component sets itself included. undefined when the style wasn't read (problem).

type Map<string, ComponentCssRead>

problem?

Why the style wasn't read, when it wasn't.

type ComponentCssProblem

ComponentCssProblem
#

svelte-css.ts view source

ComponentCssProblem

type { kind: "css_parse_failed"; message: string; line?: number; column?: number; } | { kind: "css_lang_unsupported"; message: string; lang: string; line: number; column: number; }

import type {ComponentCssProblem} from 'svelte-docinfo/svelte-css.js';

Why a component's styling API wasn't read.

ComponentCssRead
#

svelte-css.ts view source

ComponentCssRead import type {ComponentCssRead} from 'svelte-docinfo/svelte-css.js';

A custom property the component reads somewhere, as documentCssProperties checks a tag.

line

1-based line of the first read in the original source, preferring an outermost one.

type number

fallback

The value the property takes when a consumer doesn't set it: an @property rule's initial-value, else the first fallback any read gives, preferring an outermost one's.

type string | undefined

syntax?

An @property rule's syntax for the name, quotes stripped.

type string

CssVarRead
#

svelte-css.ts view source

CssVarRead import type {CssVarRead} from 'svelte-docinfo/svelte-css.js';

One var() read in CSS text.

name

The custom property's name as written, -- included.

type string

fallback

The fallback after the comma, trimmed, verbatim (comments included); undefined for a read without one, '' for var(--a,).

type string | undefined

offset

Offset of the read's var within the scanned text.

type number

fallbackRange

Offsets of the fallback's text, after the comma up to the closing ), untrimmed; undefined for a read without one.

type [start: number, end: number] | undefined

documentCssProperties
#

svelte-css.ts view source

(css: ComponentCss, tags: readonly TsdocCssProperty[], tagLineOf: (name: string) => number): DocumentedComponentCss import {documentCssProperties} from 'svelte-docinfo/svelte-css.js';

Merge a component's @cssprop tags into its styling API (ComponentDeclarationJson.cssCustomProperties, whose policy this is).

Each tag is an entry, documented: true, in tag order, ahead of the listed undocumented reads, which keep their first-read order. The tag gives description, syntax, and default; the style gives fallback and sourceLine, so the two never overwrite each other. A tagged name the component reads takes the read's line and fallback: the listed entry's when the heuristic found the name, else the first read's anywhere (ComponentCss.reads: a bare read, one nested in another's fallback, one in the markup's static style text, or one of a name the component sets itself). A read name's @property syntax stays when the tag gives none. A tagged name the component never reads is kept at its tag's line and reported in unread; a tag default that disagrees with the fallback, whitespace runs aside, is reported in mismatched. When the style wasn't read (ComponentCss.problem), every tag is kept at its tag's line and nothing is reported.

css

the component's styling API as analyzeComponentCss read it

tags

the component doc comment's @cssprop tags

type readonly TsdocCssProperty[]

tagLineOf

the 1-based line of a tag in the original source, by name

type (name: string) => number

returns

DocumentedComponentCss

DocumentedComponentCss
#

svelte-css.ts view source

DocumentedComponentCss import type {DocumentedComponentCss} from 'svelte-docinfo/svelte-css.js';

What documentCssProperties makes of a component's @cssprop tags.

properties

The styling API with the documented properties merged in.

type ComponentCssPropertyJsonInput[]

unread

The documented entries the component never reads, at their tags' lines, in tag order.

type ComponentCssPropertyJsonInput[]

mismatched

The documented entries whose tag default disagrees with the style's fallback, in tag order.

type ComponentCssPropertyJsonInput[]

findCsspropTagLine
#

svelte-css.ts view source

(svelteSource: string, start: number, end: number, name: string | undefined, occurrence?: number): number | undefined import {findCsspropTagLine} from 'svelte-docinfo/svelte-css.js';

The 1-based line, in the original source, of a @cssprop tag in a range of it (the doc comment the tags came from): the occurrenceth tag, from zero, that names name, or with name undefined, that names nothing (a malformed tag).

Tags are matched by text, line-leading only, so a mention later in a line (a // comment citing the tag, or a backticked one in prose) never takes the tag's place, and a tag written mid-line, which TS still reads, isn't found, leaving the caller's fallback line. A line-leading mention ahead of the tag can still take its place. A tag's text runs to the next line-leading tag, as the comment parser reads it (csspropTagText), so a name on the line after the tag and a default spanning lines parse as the tag does (parseCsspropTagText).

svelteSource

the full Svelte source code

type string

start

offset where the comment starts

type number

end

offset where the comment ends

type number

name

the documented property's name, or undefined for a malformed tag

type string | undefined

occurrence?

which matching tag, from zero (the second tag naming name is 1)

type number
optional default 0

returns

number | undefined

the line, or undefined when the range holds no such tag

scanCssVarReads
#

svelte-css.ts view source

(text: string, start?: number, end?: number): CssVarRead[] import {scanCssVarReads} from 'svelte-docinfo/svelte-css.js';

Scan CSS text for its outermost var() reads, in source order.

A read nested in another one's fallback isn't returned (var(--a, var(--b)) reads --a, with var(--b) its fallback), and neither is anything in a string, a comment, or an unquoted url(). The function name matches case-insensitively, as CSS does; a var( with no -- name or no closing ) reads nothing.

text

CSS text, typically a declaration's value

type string

start?

offset to start scanning at

type number
optional default 0

end?

offset to stop scanning at

type number
optional default text.length

returns

CssVarRead[]

the reads, with offsets into text

Depends on
#

Imported by
#