|
| 1 | +# fss-lang |
| 2 | + |
| 3 | +**File Style Sheets** — a CSS-like language for describing how files should be rendered in a tree or panel. |
| 4 | + |
| 5 | +## Features |
| 6 | + |
| 7 | +- **CSS-like syntax** powered by [css-tree](https://github.com/nicolo-ribaudo/css-tree) for robust parsing |
| 8 | +- **Type selectors**: `file`, `folder` |
| 9 | +- **Attribute selectors**: `[ext="ts"]`, `[name="Dockerfile"]`, `[lang="typescript"]`, `[vcs-status="modified"]` |
| 10 | +- **Attribute operators**: `=`, `^=`, `$=`, `~=`, `!=` |
| 11 | +- **Pseudo-classes**: `:expanded`, `:selected`, `:hovered`, `:active`, `:drag-over`, `:focused` |
| 12 | +- **`:root` pseudo-class**: `folder:root` matches the top-level folder |
| 13 | +- **`:is()` grouping**: `file:is([ext="ts"], [ext="tsx"])` |
| 14 | +- **Descendant combinator**: `folder[name=".github"] folder[name="workflows"]` |
| 15 | +- **Compound extensions**: `file[ext="test.ts"]` overrides `file[ext="ts"]` — specificity scales by segment count |
| 16 | +- **Language selector**: `file[lang="typescript"]` — match by VS Code language ID |
| 17 | +- **`@theme` blocks**: `light`, `dark`, `high-contrast`, `high-contrast-light` — like VS Code |
| 18 | +- **`@sorting` block** for sort priority/grouping |
| 19 | +- **`@table` block** for column visibility/width/order |
| 20 | +- **Layered resolution**: global → project → nested `.faraday` overrides |
| 21 | +- **Sub-O(N) matching** via rule indexing by name, extension, language, and type |
| 22 | +- **Style caching** for amortized O(1) per unique file signature |
| 23 | + |
| 24 | +## Install |
| 25 | + |
| 26 | +```bash |
| 27 | +npm install fss-lang |
| 28 | +``` |
| 29 | + |
| 30 | +## Quick Start |
| 31 | + |
| 32 | +```typescript |
| 33 | +import { parseStylesheet, resolveStyle, createFsNode, StateFlags } from 'fss-lang' |
| 34 | + |
| 35 | +// Parse an FSS stylesheet |
| 36 | +const sheet = parseStylesheet(` |
| 37 | + file { icon: url(default-file.svg); color: white; } |
| 38 | + folder { icon: url(default-folder.svg); } |
| 39 | + folder:expanded { icon: url(folder-open.svg); } |
| 40 | +
|
| 41 | + file[ext="ts"] { icon: url(ts.svg); color: blue; } |
| 42 | + file[ext="test.ts"] { icon: url(test.svg); badge: "T"; } |
| 43 | + file[name="Dockerfile"] { icon: url(docker.svg); } |
| 44 | +
|
| 45 | + file[lang="typescript"] { color: blue; } |
| 46 | + file:is([ext="ts"], [ext="tsx"]) { color: blue; } |
| 47 | + file[vcs-status="modified"] { color: orange; } |
| 48 | +
|
| 49 | + folder:root { icon: url(project-root.svg); } |
| 50 | +
|
| 51 | + folder[name=".github"] folder[name="workflows"] { |
| 52 | + icon: url(gh-workflow.svg); |
| 53 | + } |
| 54 | +
|
| 55 | + @sorting { |
| 56 | + file[executable] { priority: 10; } |
| 57 | + } |
| 58 | +
|
| 59 | + @table { |
| 60 | + column(size) { visible: false; } |
| 61 | + column(vcs-status) { width: 30; order: 2; } |
| 62 | + } |
| 63 | +`) |
| 64 | + |
| 65 | +// Create a file node |
| 66 | +const node = createFsNode({ |
| 67 | + type: 'file', |
| 68 | + name: 'index.ts', |
| 69 | + path: '/src/index.ts', |
| 70 | + lang: 'typescript', |
| 71 | + meta: { 'vcs-status': 'modified' }, |
| 72 | +}) |
| 73 | + |
| 74 | +// Resolve style |
| 75 | +const style = resolveStyle(sheet, node, 'dark') |
| 76 | +// → { icon: 'url(ts.svg)', color: '#58a6ff' } |
| 77 | +``` |
| 78 | + |
| 79 | +## Cached Resolution |
| 80 | + |
| 81 | +For large trees (10k+ nodes), use `CachedResolver` to avoid recomputing styles for nodes with identical signatures: |
| 82 | + |
| 83 | +```typescript |
| 84 | +import { CachedResolver, parseStylesheet } from 'fss-lang' |
| 85 | + |
| 86 | +const sheet = parseStylesheet(`...`) |
| 87 | +const resolver = new CachedResolver(sheet, 'dark') |
| 88 | + |
| 89 | +// Many .ts files share the same style — computed once, cached forever |
| 90 | +const style = resolver.resolveStyle(node) |
| 91 | + |
| 92 | +// Switch theme — cache is invalidated automatically |
| 93 | +resolver.setTheme('light') |
| 94 | +``` |
| 95 | + |
| 96 | +## Layer System |
| 97 | + |
| 98 | +Support global config with per-folder overrides (e.g. `.faraday/style.fss`): |
| 99 | + |
| 100 | +```typescript |
| 101 | +import { LayeredResolver, createLayer, LayerPriority } from 'fss-lang' |
| 102 | + |
| 103 | +const resolver = new LayeredResolver() |
| 104 | + |
| 105 | +// Global defaults |
| 106 | +resolver.addLayer(createLayer(` |
| 107 | + file { icon: url(file.svg); } |
| 108 | +`, '/', LayerPriority.GLOBAL)) |
| 109 | + |
| 110 | +// Project-specific overrides |
| 111 | +resolver.addLayer(createLayer(` |
| 112 | + file[ext="ts"] { icon: url(custom-ts.svg); } |
| 113 | +`, '/my-project/', LayerPriority.PROJECT)) |
| 114 | + |
| 115 | +// Nested folder overrides (deeper = higher priority) |
| 116 | +resolver.addLayer(createLayer(` |
| 117 | + file { icon: url(special.svg); } |
| 118 | +`, '/my-project/packages/core/', LayerPriority.nestedPriority(1))) |
| 119 | + |
| 120 | +const style = resolver.resolveStyle(node) |
| 121 | +``` |
| 122 | + |
| 123 | +## Grammar |
| 124 | + |
| 125 | +### Node Styling |
| 126 | + |
| 127 | +``` |
| 128 | +file { icon: url(file.svg); } |
| 129 | +folder { icon: url(folder.svg); } |
| 130 | +file[ext="ts"] { icon: url(ts.svg); } |
| 131 | +file[name="Dockerfile"] { icon: url(docker.svg); } |
| 132 | +file[ext$="d.ts"] { badge: "DT"; } |
| 133 | +folder:expanded { icon: url(open.svg); } |
| 134 | +file:is([ext="ts"], [ext="tsx"]) { color: blue; } |
| 135 | +file[lang="typescript"] { icon: url(ts.svg); } |
| 136 | +folder[name=".github"] folder[name="workflows"] { icon: url(gh.svg); } |
| 137 | +file[inVcsRepo] { badge: "V"; } |
| 138 | +folder:root { icon: url(project-root.svg); } |
| 139 | +``` |
| 140 | + |
| 141 | +### Themes |
| 142 | + |
| 143 | +``` |
| 144 | +@theme dark { |
| 145 | + file { color: #ccc; } |
| 146 | + file[ext="ts"] { color: #58a6ff; } |
| 147 | +} |
| 148 | +
|
| 149 | +@theme light { |
| 150 | + file { color: #333; } |
| 151 | + file[ext="ts"] { color: #0366d6; } |
| 152 | +} |
| 153 | +
|
| 154 | +@theme high-contrast { |
| 155 | + file[ext="ts"] { color: #79c0ff; font-weight: bold; } |
| 156 | +} |
| 157 | +
|
| 158 | +@theme high-contrast-light { |
| 159 | + file[ext="ts"] { color: #0969da; font-weight: bold; } |
| 160 | +} |
| 161 | +``` |
| 162 | + |
| 163 | +Supported kinds: `light`, `dark`, `high-contrast`, `high-contrast-light` (matching VS Code). |
| 164 | +Rules outside `@theme` apply in all themes. Theme-scoped rules merge on top. |
| 165 | + |
| 166 | +### Sorting |
| 167 | + |
| 168 | +``` |
| 169 | +@sorting { |
| 170 | + file[executable] { priority: 10; } |
| 171 | + folder { group-first: true; } |
| 172 | +} |
| 173 | +``` |
| 174 | + |
| 175 | +### Table Configuration |
| 176 | + |
| 177 | +``` |
| 178 | +@table { |
| 179 | + column(size) { visible: false; } |
| 180 | + column(vcs-status) { width: 30; order: 2; } |
| 181 | +} |
| 182 | +``` |
| 183 | + |
| 184 | +## Performance |
| 185 | + |
| 186 | +The engine uses **rule indexing** for sub-O(N) matching: |
| 187 | + |
| 188 | +| Technique | Benefit | |
| 189 | +|---|---| |
| 190 | +| **Bucket indexing** by name, ext, type | Only evaluate ~5–20 candidate rules instead of all | |
| 191 | +| **Bitmask state matching** | Single integer AND for pseudo-class checks | |
| 192 | +| **Style key caching** | Amortized O(1) for nodes with identical signatures | |
| 193 | +| **Pre-sorted rules** | No sorting during match phase | |
| 194 | + |
| 195 | +| **Candidate caching** | WeakMap-based per-sheet cache for nodes sharing the same bucket key | |
| 196 | + |
| 197 | +For a stylesheet with 10,000 rules and 5,000 files in the same directory, the engine evaluates only a small subset of candidate rules per node. Nodes sharing the same extension/type/name pattern reuse a cached candidate list, and `CachedResolver` further deduplicates resolution for nodes with identical style keys. |
| 198 | + |
| 199 | +## API |
| 200 | + |
| 201 | +### `parseStylesheet(source: string): CompiledStylesheet` |
| 202 | + |
| 203 | +Parse FSS source into an indexed, compiled stylesheet. |
| 204 | + |
| 205 | +### `resolveStyle(sheet: CompiledStylesheet, node: FsNode, theme?: ThemeKind): ResolvedStyle` |
| 206 | + |
| 207 | +Resolve all matching style declarations for a node. |
| 208 | +When `theme` is provided, both unscoped and matching-theme rules apply. |
| 209 | + |
| 210 | +### `resolveSorting(sheet: CompiledStylesheet, node: FsNode, theme?: ThemeKind): Record<string, FssValue>` |
| 211 | + |
| 212 | +Resolve sorting declarations for a node. |
| 213 | + |
| 214 | +### `createFsNode(opts): FsNode` |
| 215 | + |
| 216 | +Create a node with auto-computed extensions. |
| 217 | + |
| 218 | +### `CachedResolver` |
| 219 | + |
| 220 | +Style resolver with per-signature caching. Accepts optional `theme` in constructor. |
| 221 | +Call `setTheme(theme)` to switch — cache is auto-invalidated. |
| 222 | + |
| 223 | +### `LayeredResolver` |
| 224 | + |
| 225 | +Multi-layer resolver with scope-based priority. |
| 226 | +Call `setTheme(theme)` to switch — cache is auto-invalidated. |
| 227 | + |
| 228 | +### `createLayer(source, scopePath, priority): StyleLayer` |
| 229 | + |
| 230 | +Create a scoped style layer from FSS source. |
| 231 | + |
| 232 | +## License |
| 233 | + |
| 234 | +MIT |
0 commit comments