tracker

20.3 KB

1. // The framework's STYLESHEET — the Style convention of COMPONENTS §4, as the
2. // archived hl:web implemented it (archive/hlweb-v1/plugins-web/web_css.hl), re-read
3. // 2026-09-12 after a version built from the doc alone got most of it wrong.
4. //
5. // STRUCTURE FROM THE SYNTAX, VALUES FROM THE INSTANCE. A hybrid's keys come back
6. // alphabetical, so the ORDER of rules, declarations and media conditions is read
7. // off the syntax (hlSyntax entries are authored order) while every VALUE is read
8. // off the constructed instance at the same path — the language has already folded
9. // the statics (`background = dark`) and merged `base + { … }` by then.
10. //
11. // WHAT A RULE NAME MEANS (the archive's `placesFor`, per file):
12. // `@root` / `':root'` a CONTRIBUTION: collected from every file into ONE
13. // `:root { }` at the top of the sheet, in order
14. // `'@media …'` / `@media` a BLOCK of rules: collected at the END of the sheet,
15. // (`@supports`, the same shape and place for the other two queries
16. // `@container`) (ticket #66, proposal 5)
17. // one `@media` per distinct query, first-seen order;
18. // `@media { minWidth = 960 … }` composes the query from
19. // conditions (number → px, string verbatim)
20. // `'@keyframes name'` an ANIMATION: its stops (`'from'`, `to`, `'50%'`) with
21. // their declarations, emitted where it stands (ticket #66, 4)
22. // selector-shaped verbatim (`'.icon'`, `'#page-anchor'`, `'a:hover'`)
23. // referenced `Style.x` the class the View wrote (tag-prefix strip): `.x`, or
24. // `tag.stripped`
25. // `#x` id the View writes `id = 'x'` on an element: `#x` (R3)
26. // `#x` local otherwise matched by NAME to this file's elements `x` (and
27. // a composed child's root for `#Child`): `tag.<file class>`
28. // own-name a rule named like an element of this file's View (or
29. // body/html): the TAG selector, no class
30. // anything else DEAD: dropped and listed
31. // In a STYLES FILE (root members, no View) a bare name is a tag, kebab-cased.
32. // NESTED under a rule, a name of PSEUDOS is that rule's pseudo-class, not a
33. // descendant: `a { hover { … } }` → `a:hover` (ticket #66, proposal 1).
34. // A rule with no declarations and nested rules is a CONTAINER: not emitted.
35. // Two rules emitting one selector with different bodies: refused.
37. import HlwCssVar from './cssvar.hl'
39. static NL = "
40. "
41. static SELECTOR_CHARS = ":-.#>[]()*+~,/ %@=^|!"
42. static HEADER = "/* GENERATED by hl:web — ONE global stylesheet.
43. Components author their Style rules per file; only the rules a View actually
44. REFERENCES are emitted (dead rules are dropped and listed at boot). Class names
45. follow the tag-prefix strip rule: rule `headerMain` referenced inside `header`
46. emits class=\"main\" under the TAG-QUALIFIED selector `header.main`; under any
47. other tag it keeps `.headerMain`. */
48. "
50. Boolean minify = false
51. view = null // the View walk: kebab, className, localClass live there
52. gen = 0 // the analysis generation the syntax handles belong to
54. // per sheet
55. parts = []
56. seen = {}
57. dead = []
58. mediaOrder = []
59. mediaParts = []
60. rootDecls = []
62. // ---- names ----------------------------------------------------------------------
63. // ---- css variables (creator's ruling 2026-09-13) --------------------------------
64. // `bg = var('#FFF')` declares a custom property as a VALUE; the walker names it after
65. // its member, writes it into the sheet's one `:root`, and rewrites every use.
66. static counter = { n = 0 }
67. // `var('#FFF', dark = '#000')` carries its dark-scheme value too (ticket #66,
68. // proposal 2): the sheet writes it into `:root` under `(prefers-color-scheme: dark)`
69. static var = (value, dark = null) => {
70. counter.n = counter.n + 1
71. return new HlwCssVar(value = value, id = counter.n, dark = dark)
72. }
73. static DARK = '@media (prefers-color-scheme: dark)'
75. // ---- units as functions (ticket #66, proposal 3) ---------------------------------
76. // a number is emitted unitless as written; `rem(1.5)`, `px(12)`, `pct(50)` answer the
77. // TEXT with its unit — '1.5rem', '12px', '50%' — so a value says what it measures
78. static rem = (n) => { return '' + n + 'rem' }
79. static px = (n) => { return '' + n + 'px' }
80. static pct = (n) => { return '' + n + '%' }
81. vars = {} // id → { name value } for the sheet being built
82. varNames = {} // name → true
84. isVar(v) { return v != null && hlTypeName(v) == 'Instance' }
86. // the variables a file's root members declare, named after the member
87. collectVars(f) {
88. for (r of fileRules(f)) {
89. if (!r.isBlock && isVar(r.value)) {
90. r.value.name = r.key
91. vars['' + r.value.id] = { name = r.key; value = r.value.value; }
92. varNames[r.key] = true
93. }
94. }
95. // a token the file INHERITS: its own instance's copy, under the parent's name (ticket #39)
96. if (f.aliases != null) {
97. for (a of f.aliases) {
98. a.value.name = a.key
99. vars['' + a.value.id] = { name = a.key; value = a.value.value; }
100. }
101. }
102. return null
103. }
105. // a value's text with every variable reference resolved: a variable itself →
106. // var(--name); a composed string carries placeholders var(--hlv<id>) → var(--name)
107. varText(v) {
108. if (isVar(v)) {
109. let d = vars['' + v.id]
110. if (d == null) { hlError("a css variable is used before any styles file declared it as a root member — `name = var(…)` at the root of the styles file") }
111. return 'var(--' + view.kebab(d.name) + ')'
112. }
113. let s = '' + v
114. if (s.indexOf('var(--hlv') < 0) { return s }
115. for (id of vars.keys()) { s = s.replaceAll('var(--hlv' + id + ')', 'var(--' + view.kebab(vars[id].name) + ')') }
116. return s
117. }
119. // the pseudo-classes a nested entry may name, camelCase as written (kebab-cased on emit)
120. static PSEUDOS = ['hover', 'focus', 'focusVisible', 'focusWithin', 'active', 'visited', 'target',
121. 'disabled', 'enabled', 'checked', 'required', 'optional', 'valid', 'invalid', 'readOnly',
122. 'placeholderShown', 'firstChild', 'lastChild', 'onlyChild', 'firstOfType', 'lastOfType', 'empty']
123. isPseudo(name) { return PSEUDOS.includes(name) }
125. // the selectors a nested entry composes under its enclosing rule's `sels`: a
126. // pseudo-class sticks to each (`a:hover`), anything else is a descendant (`a span`)
127. nestedSels(f, sels, key) {
128. let out = []
129. if (isPseudo(key)) {
130. for (p of sels) { out.push(p + ':' + view.kebab(key)) }
131. return out
132. }
133. let kidSels = selectorsFor(f, key)
134. for (p of sels) { for (s of kidSels) { out.push(p + ' ' + s) } }
135. return out
136. }
138. isKeyframes(name) { return name == '@keyframes' || name.startsWith('@keyframes ') }
140. isRootBlock(name) { return name == '@root' || name == ':root' }
141. // THE THREE QUERIES share one shape: `@media`, `@supports`, `@container` — bare with
142. // conditions as scalars, or spelled out in the key
143. static QUERIES = ['@media', '@supports', '@container']
144. queryKind(name) {
145. for (k of QUERIES) {
146. if (name == k || name.startsWith(k + ' ') || name.startsWith(k + '(')) { return k }
147. }
148. return ''
149. }
150. isMediaBlock(name) { return queryKind(name) != '' }
151. mediaLiteral(name) { return name.slice(queryKind(name).length, name.length).trim() }
152. localName(name) { return name.startsWith('#') ? name.slice(1) : '' }
154. selectorShaped(name) {
155. if (name.length == 0) { return false }
156. if ('0123456789'.indexOf(name.charAt(0)) >= 0) { return true }
157. let i = 0
158. while (i < name.length) {
159. if (SELECTOR_CHARS.indexOf(name.charAt(i)) >= 0) { return true }
160. i = i + 1
161. }
162. return false
163. }
165. // ---- one block's syntax, with its values --------------------------------------
166. // the entries of a hybrid node: [{ key node value isBlock }] in authored order,
167. // values read off `hybrid` (the instance's evaluated member at the same path)
168. entriesOf(key, node, hybrid) {
169. let out = []
170. let n = node == 0 ? null : hlSyntax(gen, key, node)
171. if (n == null || n.tag != 'object_expression') {
172. // A MERGED RULE (`extR = baseR + { top = 'auto' }`, COMPONENTS §4: "Style gets it
173. // for free") has no literal to read: its entries are the merged VALUE's, and a
174. // nested block is read the same way. It used to read as no entries at all, so the
175. // View wrote the class and the sheet carried no rule for it (mission 322 row 9).
176. if (isHybridValue(hybrid)) {
177. for (k of hybrid.keys()) { out.push({ key = k; node = 0; value = hybrid[k]; isBlock = isHybridValue(hybrid[k]); }) }
178. }
179. return out
180. }
181. for (h of n.entries) {
182. let e = hlSyntax(gen, key, h)
183. if (e != null && e.tag == 'object_property') {
184. let v = hlSyntax(gen, key, e.value)
185. let val = hybrid != null ? hybrid[e.key] : null
186. out.push({ key = e.key; node = e.value; value = val; isBlock = v != null && (v.tag == 'object_expression' || (v.tag == 'binary_expression' && isHybridValue(val))); })
187. }
188. }
189. guardMedia(key, out)
190. return out
191. }
193. // a hybrid VALUE (a rule), as opposed to a scalar declaration or a var() token
194. isHybridValue(v) { return v != null && hlTypeName(v) == 'Hybrid' }
196. // TWO BLOCKS UNDER ONE `@media` NAME (creator, 2026-09-13; measured in the social
197. // app's styles file). This walk reads a block's STRUCTURE off the syntax but its
198. // VALUES off the CONSTRUCTED INSTANCE, by name — and a name declared twice holds
199. // one value, the second. Both blocks then read the second one's hybrid, so the
200. // first comes out with no conditions and no declarations (`@media (prefers-color-scheme: )`)
201. // and nothing in the sheet says why. Refused here rather than emitted garbled.
202. guardMedia(key, entries) {
203. let mediaSeen = {}
204. for (e of entries) {
205. if (isMediaBlock(e.key)) {
206. if (mediaSeen[e.key] != null) {
207. hlError(key + " declares '" + e.key + "' twice. A block's values are read off the constructed instance BY NAME, so the second binding is what BOTH blocks read and the first one comes out empty. Spell the two queries out as distinct keys — '@media (prefers-color-scheme: dark)' = { … } and '@media (min-width: 640px)' = { … } — or move the second block into a component's own Style")
208. }
209. mediaSeen[e.key] = true
210. }
211. }
212. return null
213. }
215. // a value as CSS text: a string as written, a number unitless, a static already
216. // folded, a css variable (or a string composed with one) resolved to var(--name)
217. text(v) {
218. return varText(v)
219. }
221. declLine(k, v) {
222. if (minify) { return view.kebab(k) + ':' + text(v) + ';' }
223. return ' ' + view.kebab(k) + ': ' + text(v) + ';' + NL
224. }
226. // a media condition: `minWidth = 960` → `(min-width: 960px)`, a string verbatim
227. condition(k, v) {
228. if (hlTypeName(v) == 'Number') { return '(' + view.kebab(k) + ': ' + v + 'px)' }
229. return '(' + view.kebab(k) + ': ' + v + ')'
230. }
232. // the whole prelude, `@media (a) and (b)`: an enclosing query of the SAME kind is
233. // joined with `and`; one of another kind cannot be, in a sheet written flat
234. queryText(kind, outer, literal, conds, name) {
235. let parts = []
236. if (outer != '') {
237. if (!outer.startsWith(kind + ' ')) { hlError("'" + name + "' stands inside '" + outer + "' — two kinds of query cannot be joined into one; write the block beside it, not inside") }
238. parts.push(outer.slice(kind.length + 1, outer.length))
239. }
240. if (literal != '') { parts.push(literal) }
241. for (c of conds) { parts.push(c) }
242. let out = ''
243. for (p of parts) { out = out == '' ? p : out + ' and ' + p }
244. return kind + ' ' + out
245. }
247. // ---- where a rule lands (the archive's placesFor) -------------------------------
248. // `f` is the file block: { key cls refs tags hasView isStyles }; refs are what the
249. // View wrote ([{ tag rule }]), tags the element names the file's own View renders.
250. selectorsFor(f, name) {
251. if (f.isStyles) {
252. if (selectorShaped(name)) { return [name] }
253. return [view.domTag(name)]
254. }
255. let local = localName(name)
256. // the View writes `id = 'x'`: `#x` is that id, nothing else (ticket #51, R3)
257. if (local != '' && f.ids != null && f.ids.includes(local)) { return [name] }
258. if (local != '' && !selectorShaped(local)) {
259. let out = []
260. for (r of f.refs) {
261. if (r.rule == name) {
262. let sel = view.domTag(r.tag) + '.' + view.localClass(f.key)
263. if (!out.includes(sel)) { out.push(sel) }
264. }
265. }
266. return out
267. }
268. if (selectorShaped(name)) { return [name] }
269. let classes = []
270. for (r of f.refs) {
271. if (r.rule == name) {
272. let cls = view.className(name, r.tag)
273. if (!classes.includes(cls)) { classes.push(cls) }
274. }
275. }
276. if (classes.length == 0) {
277. if (f.tags.includes(name) || name == 'body' || name == 'html') { return [view.domTag(name)] }
278. return []
279. }
280. let out = []
281. for (cls of classes) {
282. if (cls == name) { out.push('.' + view.kebab(cls)) }
283. else { out.push(view.domTag(name.slice(0, name.length - cls.length)) + '.' + view.kebab(cls)) }
284. }
285. return out
286. }
288. // ---- emission -------------------------------------------------------------------
289. putRule(f, name, selector, body, query) {
290. let first = seen[query + '|' + selector]
291. if (first != null) {
292. if (first.body == body) { return null }
293. hlError("style rule '" + selector + "' is emitted twice with different bodies — '" + first.rule + "' in " + first.file + " and '" + name + "' in " + f.key + " both emit that selector; put the declarations in ONE rule, or rename one of them")
294. }
295. seen[query + '|' + selector] = { body = body; rule = name; file = f.key; }
296. if (query == '') {
297. parts.push(minify ? selector + '{' + body + '}' : NL + selector + ' {' + NL + body + '}' + NL)
298. } else {
299. mediaPut(query, selector, body)
300. }
301. return null
302. }
304. mediaPut(query, selector, body) {
305. if (!mediaOrder.includes(query)) { mediaOrder.push(query) }
306. // inside a media block every line is indented two spaces (the archive's goldens)
307. let inner = minify ? selector + '{' + body + '}' : ' ' + selector + ' {' + NL + ' ' + body.replace(NL + ' ', NL + ' ') + ' }' + NL
308. mediaParts.push({ query = query; text = inner; })
309. return null
310. }
312. // ONE RULE: its own declarations under `sels`, its nested rules composed below it
313. // (descendant), its media blocks under the query; a container emits nothing itself
314. emitRule(f, name, sels, entries, query) {
315. let body = ''
316. let kids = []
317. let medias = []
318. for (e of entries) {
319. if (e.isBlock) {
320. if (isMediaBlock(e.key)) { medias.push(e) } else { kids.push(e) }
321. } else if (e.value != null) {
322. body = body + declLine(e.key, e.value)
323. }
324. }
325. if (body != '') {
326. for (sel of sels) { putRule(f, name, sel, body, query) }
327. }
328. for (k of kids) {
329. if (isKeyframes(k.key)) { hlError("'" + k.key + "' inside '" + name + "' in " + f.key + " — an animation is not a rule's child: write it at the top of the Style or of the styles file") }
330. let composed = nestedSels(f, sels, k.key)
331. if (composed.length == 0) {
332. dead.push(f.cls + '.' + name + ' ' + k.key)
333. } else {
334. emitRule(f, name + ' ' + k.key, composed, entriesOf(f.key, k.node, k.value), query)
335. }
336. }
337. for (m of medias) {
338. if (query != '') { hlError("'" + m.key + "' inside '" + name + "' is already under a query — state both conditions in ONE block") }
339. mediaBlock(f, m.key, m.node, m.value, sels, name, '')
340. }
341. return null
342. }
344. // ONE `@media` BLOCK, at the top of a Style (prefixes empty) or inside a rule
345. // (prefixes = the enclosing rule's selectors): scalar entries are CONDITIONS
346. // (only for the bare `@media` spelling), block entries are RULES under the query;
347. // inside a rule, scalar entries are the ENCLOSING RULE's declarations under it.
348. mediaBlock(f, name, node, hybrid, prefixes, outer, outerQuery) {
349. let literal = mediaLiteral(name)
350. let conds = []
351. let own = ''
352. let rules = []
353. let overrides = ''
354. for (e of entriesOf(f.key, node, hybrid)) {
355. if (e.isBlock) { rules.push(e) }
356. // a css VARIABLE re-assigned under the query: `bg = '#000'` inside
357. // `@media { prefersColorScheme = 'dark' … }` is `:root { --bg: #000 }` there
358. else if (prefixes.length == 0 && varNames[e.key] != null) { overrides = overrides + declLine('--' + view.kebab(e.key), e.value) }
359. else if (literal == '' && prefixes.length == 0) { conds.push(condition(e.key, e.value)) }
360. else if (prefixes.length > 0) { own = own + declLine(e.key, e.value) }
361. else { hlError("'" + name + "' already spells its query out, so '" + e.key + "' is a declaration directly inside an at-rule — put it in a rule inside the block") }
362. }
363. let q = queryText(queryKind(name), outerQuery, literal, conds, name)
364. if (overrides != '') { putRule(f, name, ':root', overrides, q) }
365. if (own != '') { for (sel of prefixes) { putRule(f, outer, sel, own, q) } }
366. for (r of rules) {
367. if (isMediaBlock(r.key)) { mediaBlock(f, r.key, r.node, r.value, prefixes, outer, q) }
368. else if (isKeyframes(r.key)) { hlError("'" + r.key + "' inside '" + name + "' in " + f.key + " — an animation is not scoped by a query: write it at the top of the Style or of the styles file") }
369. else {
370. let composed = prefixes.length > 0 ? nestedSels(f, prefixes, r.key) : selectorsFor(f, r.key)
371. if (composed.length == 0) { dead.push(f.cls + '.' + r.key + ' (in ' + name + ')') }
372. else { emitRule(f, r.key, composed, entriesOf(f.key, r.node, r.value), q) }
373. }
374. }
375. return null
376. }
378. // a file's rules in authored order: [{ key node value isBlock }] — a component's
379. // Style entries, or a styles file's root members (its inherits' first)
380. fileRules(f) {
381. return f.rules
382. }
384. // ONE `'@keyframes name' = { 'from' = { … } to { … } '50%' = { … } }`: every entry is
385. // a stop, its key the stop's selector verbatim, its entries declarations
386. keyframes(f, r) {
387. let name = r.key.slice(10, r.key.length).trim()
388. if (name == '') { hlError("'@keyframes' in " + f.key + " names no animation — write the name into the key: '@keyframes fade' = { 'from' = { opacity = 0 } to { opacity = 1 } }") }
389. let body = ''
390. for (st of entriesOf(f.key, r.node, r.value)) {
391. if (!st.isBlock) { hlError("'" + st.key + "' in '" + r.key + "' (" + f.key + ") is a declaration, and an animation holds stops — 'from', to, '50%' — each a block of declarations") }
392. let decls = ''
393. for (d of entriesOf(f.key, st.node, st.value)) {
394. if (d.isBlock) { hlError("'" + d.key + "' in the stop '" + st.key + "' of '" + r.key + "' (" + f.key + ") is a block — a stop holds declarations only") }
395. if (d.value != null) { decls = decls + (minify ? declLine(d.key, d.value) : ' ' + declLine(d.key, d.value)) }
396. }
397. body = body + (minify ? st.key + '{' + decls + '}' : ' ' + st.key + ' {' + NL + decls + ' }' + NL)
398. }
399. putRule(f, r.key, '@keyframes ' + name, body, '')
400. return null
401. }
403. // ---- the sheet ------------------------------------------------------------------
404. // `files` are the blocks in cascade order: the styles file (with its inherits
405. // walked first by the caller), then every served component.
406. sheet(files) {
407. parts = []
408. seen = {}
409. dead = []
410. mediaOrder = []
411. mediaParts = []
412. rootDecls = []
413. vars = {}
414. varNames = {}
415. for (f of files) { collectVars(f) }
416. // the declared variables come first in :root, in declaration order; their dark
417. // values open the dark-scheme query with a :root of their own (an explicit
418. // `@media { prefersColorScheme = 'dark' … }` re-assignment lands after it and wins)
419. let darkBody = ''
420. for (f of files) {
421. for (r of fileRules(f)) {
422. if (!r.isBlock && isVar(r.value)) {
423. rootDecls.push(declLine('--' + view.kebab(r.key), r.value.value))
424. if (r.value.dark != null) { darkBody = darkBody + declLine('--' + view.kebab(r.key), r.value.dark) }
425. }
426. }
427. }
428. if (darkBody != '') { mediaPut(DARK, ':root', darkBody) }
429. for (f of files) {
430. for (r of fileRules(f)) {
431. if (!r.isBlock) {
432. // a scalar root member of a styles file is not a rule (a variable was taken above)
433. } else if (isMediaBlock(r.key)) {
434. mediaBlock(f, r.key, r.node, r.value, [], '', '')
435. } else if (isKeyframes(r.key)) {
436. keyframes(f, r)
437. } else if (isRootBlock(r.key)) {
438. for (d of entriesOf(f.key, r.node, r.value)) {
439. if (d.isBlock) { hlError("'" + r.key + "' holds custom properties only — '" + d.key + "' is a rule; put it beside the block, not inside it") }
440. rootDecls.push(declLine(d.key, d.value))
441. }
442. } else {
443. let sels = selectorsFor(f, r.key)
444. if (sels.length == 0) { dead.push(f.cls + '.' + r.key + ' bound to nothing (no reference, no matching element)') }
445. else { emitRule(f, r.key, sels, entriesOf(f.key, r.node, r.value), '') }
446. }
447. }
448. }
449. let out = minify ? '' : HEADER
450. if (rootDecls.length > 0) {
451. let body = ''
452. for (d of rootDecls) { body = body + d }
453. out = out + (minify ? ':root{' + body + '}' : NL + ':root {' + NL + body + '}' + NL)
454. }
455. for (p of parts) { out = out + p }
456. for (q of mediaOrder) {
457. let inner = ''
458. for (p of mediaParts) { if (p.query == q) { inner = inner + p.text } }
459. out = out + (minify ? q + '{' + inner + '}' : NL + q + ' {' + NL + inner + '}' + NL)
460. }
461. if (dead.length > 0) {
462. for (d of dead) { console.log('style DROPPED: ' + d) }
463. }
464. return out
465. }