@starci/eslint-canon-fe 8.4.43 → 9.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (53) hide show
  1. package/CHANGELOG.md +14 -1
  2. package/README.md +36 -84
  3. package/brand-values.mjs +1 -1
  4. package/docs/hooks-folder.md +5 -3
  5. package/docs/native-controls.md +1 -5
  6. package/docs/next-conventions.md +8 -8
  7. package/docs/size-and-state-budget.md +22 -0
  8. package/docs/surface-rules.md +11 -9
  9. package/drawing.mjs +4 -66
  10. package/hooks-folder.mjs +5 -3
  11. package/index.mjs +7 -25
  12. package/landmark.mjs +0 -3
  13. package/lib/class-text.mjs +29 -0
  14. package/lib/config.mjs +4 -6
  15. package/lib/drawing-scope.mjs +15 -0
  16. package/lib/typed-class-values.mjs +10 -1
  17. package/lib/why.mjs +10 -40
  18. package/next-conventions.mjs +33 -16
  19. package/package.json +4 -3
  20. package/runtime/knowledge/grammars/index.yaml +102 -0
  21. package/runtime/knowledge/hfs/canon-pins.yaml +22 -8
  22. package/runtime/knowledge/hfs/fe-stack.yaml +7 -0
  23. package/runtime/knowledge/hfs/slots.yaml +3 -3
  24. package/runtime/modules/kernel/removed-vocabulary.yaml +29 -0
  25. package/runtime/scripts/hfs/architecture/config.mjs +8 -8
  26. package/runtime/scripts/hfs/declaration-shape.mjs +8 -2
  27. package/runtime/scripts/hfs/rule-catalog.mjs +2 -2
  28. package/runtime/scripts/hfs/slots.mjs +1 -0
  29. package/runtime/scripts/hfs/view.mjs +1 -0
  30. package/runtime/scripts/lib/grammar-lint.mjs +48 -0
  31. package/size-and-state-budget.mjs +116 -4
  32. package/surface-rules.mjs +159 -26
  33. package/tokens.mjs +5 -217
  34. package/app-shell.mjs +0 -161
  35. package/docs/app-shell.md +0 -50
  36. package/docs/grammar-boundary.md +0 -57
  37. package/docs/status-colors.md +0 -32
  38. package/grammar-boundary.mjs +0 -203
  39. package/icon.mjs +0 -310
  40. package/lib/app-shell-cluster.mjs +0 -66
  41. package/lib/app-shell-create.mjs +0 -33
  42. package/lib/app-shell-owner-source.mjs +0 -124
  43. package/lib/app-shell-owner.mjs +0 -65
  44. package/lib/app-shell-scope.mjs +0 -79
  45. package/lib/app-shell-visible.mjs +0 -92
  46. package/lib/app-shell.mjs +0 -148
  47. package/lib/status-tones.generated.mjs +0 -9
  48. package/menu-entries.mjs +0 -133
  49. package/runtime/modules/goal/source-phrases.yaml +0 -95
  50. package/runtime/scripts/lib/source-phrases.mjs +0 -34
  51. package/status-colors.mjs +0 -137
  52. package/typography.mjs +0 -78
  53. package/vendor-boundary.mjs +0 -26
package/tokens.mjs CHANGED
@@ -1,33 +1,5 @@
1
- import { existsSync, readFileSync } from "node:fs"
2
- import { join } from "node:path"
3
-
4
- /**
5
- * The rules that hold `tokens.md`.
6
- *
7
- * THE UNION DOES MOST OF THIS, AND THESE RULES COVER WHAT IT CANNOT SEE. Every tier above the
8
- * leaves takes its classes from a typed entry, so an off-scale value there does not fail review -
9
- * it fails to compile, and there is nothing left to patrol. The leaf folder writes its own classes
10
- * and is exempt from the entry rules by policy, which makes it the one place a fractional step or a
11
- * bracketed length can still be typed. That folder is what these rules are for.
12
- *
13
- * THEY READ CONSTANTS AS WELL AS MARKUP. The last off-scale value in the source these were written
14
- * for lived in a module constant - `size-3.5` in one leaf, and a `py-1.5` in another - where every
15
- * rule that only walked JSX attributes looked straight past it. Hoisting hides a value; it does not
16
- * license one.
17
- */
18
-
19
- import { isClassAttribute, staticText } from "./lib/ast.mjs"
20
- import { hfsOf } from "./lib/hfs.mjs"
21
- import { classOf, isProductSource } from "./lib/scope.mjs"
22
-
23
- /**
24
- * A fractional step, in any family that measures.
25
- *
26
- * The rungs are whole and unevenly spaced, so half of one is not "between two rungs" - it is off
27
- * the ladder, and it will match nothing else on any screen.
28
- */
29
- const FRACTIONAL =
30
- /\b(?:gap|gap-x|gap-y|p|px|py|pt|pb|pl|pr|m|mx|my|mt|mb|ml|mr|space-x|space-y|inset|top|bottom|left|right|size|w|h)-\d+\.\d+\b/
1
+ /** Universal closed-token discipline, independent of a Grammar scale. */
2
+ import { classTextVisitors } from "./lib/class-text.mjs"
31
3
 
32
4
  /** A bracketed length: a value chosen once, for one screen, findable by nobody. */
33
5
  const ARBITRARY_LENGTH =
@@ -36,67 +8,6 @@ const ARBITRARY_LENGTH =
36
8
  /** A raw colour, which escapes the semantic palette even when it matches it today. */
37
9
  const RAW_COLOUR = /\b(?:text|bg|border|ring|from|to|via|fill|stroke|shadow|decoration)-\[#[0-9a-fA-F]/
38
10
 
39
- /** Large text. Paired with a heavy weight it is a heading, whatever element carries it. */
40
- const LARGE_TEXT = /\btext-(?:xl|2xl|3xl|4xl|5xl)\b/
41
-
42
- /** A heavy weight. */
43
- const HEAVY_WEIGHT = /\bfont-(?:bold|extrabold|black)\b/
44
-
45
- /** Static string carried by a JSX attribute, a module constant, or an array of class strings. */
46
- const classText = (value) => {
47
- if (value?.type === "JSXExpressionContainer") return classText(value.expression)
48
- if (value?.type === "ArrayExpression") {
49
- const members = value.elements.map((element) => classText(element)).filter(Boolean)
50
- return members.length > 0 ? members.join(" ") : null
51
- }
52
- return staticText(value)
53
- }
54
-
55
- /** Walk every place a class string can be written: markup, a constant, or an entry's array. */
56
- const classTextVisitors = (context, report) => {
57
- // Product source is a file of a product tier (a slot says so); tooling and config are out of scope.
58
- if (!isProductSource(context)) return {}
59
- return {
60
- JSXAttribute(node) {
61
- if (!isClassAttribute(node)) return
62
- report(node, classText(node.value))
63
- },
64
- VariableDeclarator(node) {
65
- report(node, classText(node.init))
66
- },
67
- Property(node) {
68
- if (node.computed) return
69
- const key = node.key.type === "Identifier" ? node.key.name : null
70
- if (key !== "classes") return
71
- report(node, classText(node.value))
72
- },
73
- }
74
- }
75
-
76
- // -- TOKEN-3 ---------------------------------------------------------------------------------------
77
-
78
- /** A fractional step is off the ladder, not between two rungs. */
79
- export const noFractionalStep = {
80
- meta: {
81
- type: "problem",
82
- docs: { description: "A measurement takes a whole rung; a fractional step is off the scale." },
83
- schema: [],
84
- messages: {
85
- fractional:
86
- "`{{cls}}` is half a rung. The scale is whole steps, unevenly spaced, so this is not between two rungs - it is off the ladder, and it will match nothing else on any screen. Use the nearest rung; there is no case where the right answer is half of one.",
87
- },
88
- },
89
- create(context) {
90
- return classTextVisitors(context, (node, text) => {
91
- if (!text) return
92
- const hit = text.match(FRACTIONAL)
93
- if (hit) context.report({ node, messageId: "fractional", data: { cls: hit[0] } })
94
- })
95
- },
96
- }
97
-
98
- // -- TOKEN-4 ---------------------------------------------------------------------------------------
99
-
100
11
  /** An arbitrary value escapes the system, whatever it happens to evaluate to. */
101
12
  export const noArbitraryValue = {
102
13
  meta: {
@@ -121,131 +32,8 @@ export const noArbitraryValue = {
121
32
  },
122
33
  }
123
34
 
124
- // -- TOKEN-5 ---------------------------------------------------------------------------------------
125
-
126
- /** Large text plus a heavy weight is a heading, and headings come from the component that owns both. */
127
- export const noHandRolledHeading = {
128
- meta: {
129
- type: "problem",
130
- docs: { description: "A heading comes from the heading component, not from raw type classes." },
131
- schema: [],
132
- messages: {
133
- heading:
134
- "Large text and a heavy weight together are a heading, whatever element carries them - and assembled here it is a heading nothing else knows about: the outline a screen reader builds does not contain it, and it stays behind the day the type scale changes. Render the heading component, which owns the tag and the size as one decision.",
135
- },
136
- },
137
- create(context) {
138
- return classTextVisitors(context, (node, text) => {
139
- if (!text) return
140
- if (LARGE_TEXT.test(text) && HEAVY_WEIGHT.test(text)) {
141
- context.report({ node, messageId: "heading" })
142
- }
143
- })
144
- },
145
- }
146
-
147
- /**
148
- * The class families whose names are PROMISES about a theme token, and the variable each needs.
149
- *
150
- * Tailwind resolves `max-w-app-lg` by looking for `--container-app-lg`. Nothing warns when that
151
- * variable does not exist: the class is emitted, the element gets no width, and the type system
152
- * is satisfied because the name IS in the union. That is the failure this rule exists for - a
153
- * class can be typesafe and mean nothing at the same time, and the union is exactly what makes
154
- * it look settled.
155
- *
156
- * Only families whose token name is DERIVABLE from the class name are listed. A colour or a
157
- * spacing step resolves through Tailwind's own scale as well as the theme, so a rule guessing at
158
- * those would report classes that work.
159
- */
160
- /**
161
- * Names Tailwind resolves ITSELF, which therefore promise nothing about this theme.
162
- *
163
- * `min-h-screen` is the viewport, not a variable; so are `full`, `fit`, `auto` and the viewport
164
- * units. Reported as unresolved tokens they would send an author to define `--min-height-screen`,
165
- * which is a variable nothing reads - the rule would have invented work and broken a working class.
166
- * Measured on both repositories the first time this ran: two findings, both wrong, both this list.
167
- */
168
- const TAILWIND_OWN_NAMES = new Set([
169
- "screen", "full", "fit", "auto", "none", "min", "max", "prose",
170
- "dvh", "svh", "lvh", "dvw", "svw", "lvw", "px",
171
- ])
172
- const TOKEN_CLASS_FAMILIES = [
173
- { pattern: /^max-w-app-([a-z0-9]+)$/, variable: (name) => `--container-app-${name}` },
174
- { pattern: /^max-h-([a-z][a-z0-9-]*)$/, variable: (name) => `--max-height-${name}` },
175
- { pattern: /^min-h-([a-z][a-z0-9-]*)$/, variable: (name) => `--min-height-${name}` },
176
- ]
177
-
178
- /**
179
- * The stylesheets an app declares its theme in: the route slot's `globals.css` (`fe.route`, named by its `allows`) and the brand slot's
180
- * `brand.css` (`fe.modules.brand`), both with `<app>` filled from the linted file's slot. Null when the file belongs to no app
181
- * (a shared package has no theme of its own).
182
- */
183
- /** Every theme read once per lint run. */
184
- const themeCache = new Map()
185
- const themeText = (context) => {
186
- const hfs = hfsOf(context)
187
- const app = classOf(context).bindings?.app
188
- if (app === undefined) return null
189
- const candidates = [
190
- join(hfs.slot("fe.route").path.replace("<app>", app), "globals.css"),
191
- hfs.slot("fe.modules.brand").path.replace("<app>", app),
192
- ].map((relative) => join(hfs.repoRoot, relative))
193
- const key = candidates.join("|")
194
- if (!themeCache.has(key)) {
195
- const found = candidates.filter((candidate) => existsSync(candidate)).map((candidate) => readFileSync(candidate, "utf8"))
196
- themeCache.set(key, found.length > 0 ? found.join("\n") : null)
197
- }
198
- return themeCache.get(key)
199
- }
200
-
201
- /** A class naming a token the theme never defines is a class that draws nothing. */
202
- export const noUnresolvedTokenClass = {
203
- meta: {
204
- type: "problem",
205
- docs: { description: "A class naming a theme token resolves only when the theme defines it." },
206
- schema: [],
207
- messages: {
208
- unresolved:
209
- "`{{value}}` reads as a token this theme defines, and `{{variable}}` is defined nowhere in it. Tailwind emits the class, the element gets nothing, and both the union and the compiler stay happy - which is why this is the one dead class no type can catch. Define `{{variable}}` in the stylesheet, or name a token that exists.",
210
- },
211
- },
212
- create(context) {
213
- if (!isProductSource(context)) return {}
214
- const theme = themeText(context)
215
- // A reader that cannot find the stylesheet stays quiet rather than calling every token dead.
216
- if (theme === null) return {}
217
- // The visitor hands (node, text) in that order; reversing them here is how a rule reports the
218
- // node as its message and the message as its node, and neither complains.
219
- const check = (node, value) => {
220
- for (const raw of String(value).split(/\s+/)) {
221
- const bare = raw.replace(/^[a-z-]+:/, "").replace(/^!/, "")
222
- for (const family of TOKEN_CLASS_FAMILIES) {
223
- const match = family.pattern.exec(bare)
224
- if (match === null) continue
225
- if (TAILWIND_OWN_NAMES.has(match[1])) continue
226
- const variable = family.variable(match[1])
227
- if (theme.includes(variable)) continue
228
- context.report({ node, messageId: "unresolved", data: { value: bare, variable } })
229
- }
230
- }
231
- }
232
- return classTextVisitors(context, check)
233
- },
234
- }
235
-
236
- /** The rules this law contributes to the plugin. */
237
- export const rules = {
238
- "no-fractional-step": noFractionalStep,
239
- "no-arbitrary-value": noArbitraryValue,
240
- "no-hand-rolled-heading": noHandRolledHeading,
241
- "no-unresolved-token-class": noUnresolvedTokenClass,
242
- }
35
+ /** Rules of universal token discipline. */
36
+ export const rules = { "no-arbitrary-value": noArbitraryValue }
243
37
 
244
- /**
245
- * The level this law asks for, as the plugin's own opinion.
246
- *
247
- * All three match on shape rather than judgement, so none carries the false-positive risk that
248
- * would justify adopting it at `warn`. A repository with history should expect the arbitrary-value
249
- * rule to report most: a bracketed length is the usual shape of a one-off fix.
250
- */
38
+ /** Every token-discipline rule is mandatory. */
251
39
  export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]))
package/app-shell.mjs DELETED
@@ -1,161 +0,0 @@
1
- /** FE-APP-SHELL-1..5: static app-frame and visible navbar composition from the UI canon. */
2
- import { isProductSource } from "./lib/scope.mjs"
3
- import { grammarName, isBarControl, propOf, resolveLocal, semanticText, textProp } from "./lib/app-shell.mjs"
4
- import { appBarOpenings, isAppBar, isAppShell, isNavigationDrawer, ownsAppFrame } from "./lib/app-shell-scope.mjs"
5
- import { visitVisible } from "./lib/app-shell-visible.mjs"
6
- import { clusterAlternatives } from "./lib/app-shell-cluster.mjs"
7
- import { isCreateAction, menuHasCreate } from "./lib/app-shell-create.mjs"
8
- import { provesImportedBar } from "./lib/app-shell-owner.mjs"
9
- import { variableOf } from "./lib/bindings.mjs"
10
-
11
- const CANON = "knowledge/ui/composition/app-shell.yaml"
12
- const BOTTOM_TABS = /^(?:BottomNav|BottomNavigation|BottomTabBar|MobileBottomNav|MobileTabBar)$/
13
- const EXPECTED_CLUSTER = ["language:IconButton", "theme:Switch", "notifications:IconButton", "account:AvatarButton"]
14
-
15
- const meta = (code, description, messages) => ({
16
- type: "problem",
17
- docs: { description: `${code}: ${description}`, url: CANON },
18
- schema: [],
19
- messages,
20
- })
21
-
22
- /** The app frame is the fixed-viewport Grammar shell; hand-written frame landmarks are rejected. */
23
- export const appShellFrame = {
24
- meta: meta("FE_APP_SHELL_FRAME", "FE-APP-SHELL-1 uses WorkspaceShell viewport=fixed.", {
25
- frame: "FE_APP_SHELL_FRAME: compose the app frame with WorkspaceShell viewport=\"fixed\"; Grammar owns its header, navigation and independent scroll regions.",
26
- }),
27
- create(context) {
28
- if (!isProductSource(context)) return {}
29
- return { JSXOpeningElement(node) {
30
- const wrongViewport = isAppShell(context, node) && textProp(context, node, "viewport") !== "fixed"
31
- const handFrame = ownsAppFrame(context, node) && (node.name.type === "JSXIdentifier" && ["header", "nav", "main"].includes(node.name.name) || isAppBar(context, node) && !appBarOpenings(context).has(node))
32
- if (wrongViewport || handFrame) {
33
- context.report({ node, messageId: "frame" })
34
- }
35
- } }
36
- },
37
- }
38
-
39
- /** Bottom navigation is not an alternative compact app-shell frame. */
40
- export const noShellBottomTabs = {
41
- meta: meta("FE_APP_SHELL_BOTTOM_TABS", "FE-APP-SHELL-4 keeps mobile navigation in the sidebar drawer.", {
42
- bottom: "FE_APP_SHELL_BOTTOM_TABS: the app shell uses a mobile subnav opener and Sidebar drawer. Remove bottom tab navigation and WorkspaceShell compactNavigation.",
43
- }),
44
- create(context) {
45
- if (!isProductSource(context)) return {}
46
- return { JSXOpeningElement(node) {
47
- const name = grammarName(context, node)
48
- const compact = name === "WorkspaceShell" && propOf(context, node, "compactNavigation")
49
- const value = compact && resolveLocal(context, compact.value)
50
- const absent = value?.type === "Identifier" && value.name === "undefined" && !variableOf(context, value)?.defs.length
51
- if (BOTTOM_TABS.test(name ?? "") || compact && !absent && (!compact.known || compact.value !== null || compact.present)) context.report({ node, messageId: "bottom" })
52
- } }
53
- },
54
- }
55
-
56
- const visitBar = (context, node, visit) => {
57
- const name = grammarName(context, node)
58
- if (name === "WorkspaceShell" && isAppShell(context, node)) {
59
- for (const slot of ["header", "compactHeader"]) visitVisible(context, propOf(context, node, slot).value, visit)
60
- } else if (isAppBar(context, node)) {
61
- visitVisible(context, node.parent, visit)
62
- } else if (isNavigationDrawer(context, node)) {
63
- visitVisible(context, propOf(context, node, "trigger").value, visit)
64
- }
65
- }
66
-
67
- const delegatesImportedBar = (context, expression) => {
68
- let imported = false
69
- let controls = false
70
- let unknown = false
71
- visitVisible(context, expression, (opening, name) => {
72
- if (isBarControl(context, opening, name)) controls = true
73
- if (name !== null) return
74
- const proof = provesImportedBar(context, opening)
75
- if (proof === true) imported = true
76
- if (proof === false) unknown = true
77
- })
78
- return imported && !controls && !unknown
79
- }
80
-
81
- /** Every visible control in a navbar band uses the shared control size. */
82
- export const navbarControlSize = {
83
- meta: meta("FE_NAVBAR_CONTROL_SIZE", "FE-APP-SHELL-2 requires size=control on bar controls.", {
84
- control: "FE_NAVBAR_CONTROL_SIZE: {{name}} in the navbar band needs size=\"control\" so every bar control shares Grammar's control height.",
85
- }),
86
- create(context) {
87
- if (!isProductSource(context)) return {}
88
- const reported = new Set()
89
- return { JSXOpeningElement(node) {
90
- visitBar(context, node, (control, name) => {
91
- if (!isBarControl(context, control, name) || textProp(context, control, "size") === "control" || reported.has(control)) return
92
- reported.add(control)
93
- context.report({ node: control, messageId: "control", data: { name } })
94
- })
95
- } }
96
- },
97
- }
98
-
99
- /** The right cluster is checked at the bar's actions composition, in visual source order. */
100
- export const navbarCluster = {
101
- meta: meta("FE_NAVBAR_CLUSTER", "FE-APP-SHELL-3 fixes navbar action kinds and order.", {
102
- cluster: "FE_NAVBAR_CLUSTER: navbar actions must be a tertiary Language IconButton in DropdownMenu, theme Switch, notification IconButton in Popover, account AvatarButton in DropdownMenu, in that order. Mobile retains notifications then account and moves language/theme into the drawer.",
103
- }),
104
- create(context) {
105
- if (!isProductSource(context)) return {}
106
- return { JSXOpeningElement(node) {
107
- const name = grammarName(context, node)
108
- if (!isAppShell(context, node) && !isAppBar(context, node)) return
109
- const shellHeader = name === "WorkspaceShell"
110
- const actions = propOf(context, node, shellHeader ? "header" : "actions")
111
- const { alternatives, ownsBar } = clusterAlternatives(context, actions.value, shellHeader)
112
- if (ownsBar) return
113
- if (shellHeader && delegatesImportedBar(context, actions.value)) return
114
- const desktop = EXPECTED_CLUSTER.join("|")
115
- const mobile = EXPECTED_CLUSTER.slice(2).join("|")
116
- const sequences = alternatives.map((sequence) => sequence.join("|"))
117
- if (!sequences.includes(desktop) || sequences.some((sequence) => sequence !== desktop && sequence !== mobile)) context.report({ node, messageId: "cluster" })
118
- } }
119
- },
120
- }
121
-
122
- /** Creation belongs to its page, never to the global app bar. */
123
- export const noNavbarCreate = {
124
- meta: meta("FE_NAVBAR_CREATE", "FE-APP-SHELL-5 keeps create actions on pages.", {
125
- create: "FE_NAVBAR_CREATE: move this create action from the navbar to its page.",
126
- }),
127
- create(context) {
128
- if (!isProductSource(context)) return {}
129
- const reported = new Set()
130
- const report = (node) => {
131
- if (reported.has(node)) return
132
- reported.add(node)
133
- context.report({ node, messageId: "create" })
134
- }
135
- const inspect = (control, name) => {
136
- if (name === "DropdownMenu" || name === "Popover") {
137
- if (["entries", "items", "sections"].some((slot) => menuHasCreate(context, propOf(context, control, slot).value))) report(control)
138
- visitVisible(context, propOf(context, control, "content").value, inspect)
139
- for (const child of control.parent.children) visitVisible(context, child, inspect)
140
- }
141
- if (!isBarControl(context, control, name) || reported.has(control)) return
142
- const text = `${semanticText(context, control)} ${control.parent.children.map((child) => context.sourceCode.getText(child)).join(" ")}`
143
- if (isCreateAction(text)) report(control)
144
- }
145
- return { JSXOpeningElement(node) {
146
- visitBar(context, node, inspect)
147
- } }
148
- },
149
- }
150
-
151
- /** Every app-shell enforcer is gathered into the ordinary FE lint and gate path. */
152
- export const rules = {
153
- "app-shell-frame": appShellFrame,
154
- "no-shell-bottom-tabs": noShellBottomTabs,
155
- "navbar-control-size": navbarControlSize,
156
- "navbar-cluster": navbarCluster,
157
- "no-navbar-create": noNavbarCreate,
158
- }
159
-
160
- /** Every rule is mandatory. */
161
- export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]))
package/docs/app-shell.md DELETED
@@ -1,50 +0,0 @@
1
- # App shell
2
-
3
- Owner: knowledge/ui/composition/app-shell.yaml
4
-
5
- The application composes `WorkspaceShell viewport="fixed"`. The `app-shell-frame` rule identifies
6
- workspace chrome from a fixed shell, sidebar/navigation slot, workspace identity, HFS layout owner,
7
- or a shell owner combining a bar and sidebar. It rejects hand-written app-frame landmarks and
8
- workspace shells without the fixed viewport. Generic flow-based site chrome stays in its own scope.
9
- `no-shell-bottom-tabs` rejects bottom navigation components and the shell's `compactNavigation` slot.
10
-
11
- The `navbar-cluster` rule reads the visible `TopBar` or `NavigationFeatureNav` actions in source order:
12
- tertiary Language `IconButton` triggering `DropdownMenu`, theme `Switch`, notification `IconButton`
13
- triggering `Popover`, account `AvatarButton` triggering `DropdownMenu`. It follows
14
- local JSX constants and components, constant object members, imported Grammar aliases, and namespace imports. Translated
15
- labels may be dynamic; icon sources identify language and notifications. Menu contents and popover
16
- content belong to their overlays and are outside the bar's control sequence. Conditional render
17
- branches are checked separately. Grammar `TopBar` and `NavigationFeatureNav` compositions are app
18
- bars by default. A proven `WorkspaceShell viewport="flow"` with no workspace/sidebar evidence owns
19
- generic site chrome. A shell hosting an imported navbar delegates only after its owned public
20
- export and rendered Base chain prove a `TopBar` or `NavigationFeatureNav` in every alternative.
21
- Workspace exports resolve back to source. Raw or unknown imported headers are red; the actual
22
- bar's own actions are checked where composed. Each lint source snapshot has fresh dependency proofs.
23
-
24
- `navbar-control-size` requires `size="control"` on each bar control. Unknown trailing prop spreads
25
- cannot prove a size; put the explicit size after a spread. A left `Drawer` containing
26
- `Sidebar presentation="drawer"` also identifies a mobile bar opener when composed in a separate
27
- client owner. Its trigger is checked; drawer bodies and footers retain their normal field sizes.
28
- `no-navbar-create` places creation on its
29
- own page and rejects create controls in the navbar and its attached menus or popovers. Static
30
- evidence includes literal labels, translated keys with create semantics, and conventional create
31
- handlers. Runtime-generated labels and arbitrary handler behavior need semantic review; the rule
32
- does not execute application code.
33
-
34
- | Rule | Invalid composition | Valid composition |
35
- | --- | --- | --- |
36
- | `app-shell-frame` | An app `Shell` returns a hand-written `<header>` and `<nav>`. | `WorkspaceShell viewport="fixed"` owns the app frame. |
37
- | `no-shell-bottom-tabs` | The shell supplies `compactNavigation={<BottomNav />}`. | The shell supplies `navigationDrawer` with a drawer `Sidebar`. |
38
- | `navbar-control-size` | A navbar `IconButton` uses `size="md"`. | The same control uses `size="control"`. |
39
- | `navbar-cluster` | Account precedes notifications, or a language trigger uses a regular `Button`. | Language menu, theme switch, notification popover, account menu use their stated Grammar trigger kinds in that order. |
40
- | `no-navbar-create` | A navbar button or attached menu item creates a record. | The page owns its create action. |
41
-
42
- ```tsx
43
- // Invalid: the navbar action creates a page record and has a different height.
44
- <TopBar actions={<Button onPress={on.create}>Create</Button>} />
45
-
46
- // Valid: a page action belongs to page content.
47
- <SurfaceCard><Button onPress={on.create}>Create</Button></SurfaceCard>
48
- ```
49
-
50
- All five rules are errors in the gathered FE canon and run through the ordinary application gate.
@@ -1,57 +0,0 @@
1
- # Grammar boundary
2
-
3
- Law module: `grammar-boundary.mjs`. Catalogue: R62 FE_NATIVE_FORM_CONTROL (the grammar owns the element), R65 FE_SIZE_AND_STATE_BUDGET (timer ownership).
4
-
5
- Page structure and text are composed from `@starci/grammar` (or the repository's `<family>-ui` package), not drawn as raw HTML.
6
-
7
- Every rule below is an error in `starciFeConfig`; none can be switched off or suppressed inline.
8
-
9
- ## `starci-fe/no-raw-structural-element`
10
-
11
- Page structure and text are grammar components, not raw `div`-family HTML; only `fe.package.ui` renderers draw raw tags.
12
-
13
- Applies to app source that composes the grammar (slots `fe.feature`, `fe.components`, `fe.route`, `fe.hooks`) and to every workspace package except the `<family>-ui` package (`fe.package.ui`), whose components are the renderers. Spec files render raw HTML as a harness and are not judged; a file no slot owns is not judged.
14
-
15
- The refused tags are exactly those `@starci/grammar` has a component for (the twin test reads the package source): `h1-h6` (`Heading`), `p` and `span` (`Text`), `hr` (`Divider`), `label` (`Label`), `form` (`Form`), `fieldset` (`Fieldset`), `dl` `dt` `dd` (`DescriptionList`), `table` `thead` `tbody` `tr` `td` `th` (`DataTable`), `ul` `ol` `li` (`List` and `ListItem` for a plain semantic list, `SurfaceListCard`, `StaticStateRow`), `header` (`SectionHeader`, `TopBar`), `footer` (`Footer`), `nav` (`NavLandmark` for a named row of links, `Subnav`, `Breadcrumbs`, `NavigationFeatureNav`), `section` (`Region` for a named non-card region, `SurfaceCard`), `main` (`WorkspaceShell`), `figure` and `figcaption` (`MediaFrame`). `div`, `br`, `aside` and `article` are not refused: the grammar has no component for them.
16
-
17
- Native `<time>` remains available for an absolute timestamp. Live relative time and countdown labels use `RelativeTime`.
18
-
19
- **Invalid** (`src/features/pages/home/component.tsx`)
20
-
21
- ```ts
22
- export const Home = () => <section><p>{t("intro")}</p></section>
23
- ```
24
-
25
- **Valid** (`src/features/pages/home/component.tsx`)
26
-
27
- ```ts
28
- export const Home = () => <SurfaceCard><Text>{t("intro")}</Text></SurfaceCard>
29
- ```
30
-
31
- **Finding code:** `FE_NATIVE_FORM_CONTROL`
32
-
33
- **Why:** Raw `<tag>` in `<file>`. Page structure and text are composed from grammar components, not written as raw HTML.
34
-
35
- **Fix:** Replace it with the matching grammar component (`Heading`, `Text`, `SurfaceCard`, ...); if the grammar lacks one, add it to the grammar or the ui package instead of drawing it in place.
36
-
37
- ## `starci-fe/no-app-relative-clock`
38
-
39
- Grammar owns the shared clock for live relative time and countdowns. App components, hooks, modules and shared packages, including a product UI package, pass `dateTime`, `locale` and `mode` to `RelativeTime`.
40
-
41
- The rule rejects a recurring `setInterval` or self-scheduling `setTimeout` whose callback or same-file helper reads `Date.now()`, `Date()`, zero-argument `new Date()` or `performance.now()`. It follows local aliases and destructured platform methods. Static reads, one-shot delays and timers that do not read the clock remain available. Indirect external clock helpers and counters that only decrement state need semantic review.
42
-
43
- **Invalid** (`src/hooks/time/useNow.ts`)
44
-
45
- ```ts
46
- const timer = setInterval(() => update(Date.now()), 1000)
47
- ```
48
-
49
- **Valid** (`src/components/leaves/UpdatedAt/index.tsx`)
50
-
51
- ```tsx
52
- const UpdatedAt = () => <RelativeTime dateTime={instant} locale={locale} mode="relative" />
53
- ```
54
-
55
- **Finding code:** `FE_SIZE_AND_STATE_BUDGET`
56
-
57
- **Fix:** Render the Grammar primitive and pass the instant; its single shared ticker owns updates and its deterministic fallback owns the server render.
@@ -1,32 +0,0 @@
1
- # Status colours: text and icons take the soft pair
2
-
3
- Law module: `status-colors.mjs`. Catalogue: R61 FE_STYLE_TOKEN_ONLY (the class-name half of the soft-pair contrast obligation; the brand layer's own contrast is `starci/status-contrast` of @starci/stylelint-canon).
4
-
5
- A status tone has two faces. The solid tone (`--success`) is a fill, with `--success-foreground` ink on it. A status shown as text or as an icon takes the soft pair, the way a HeroUI flat Chip does: `--success-soft-foreground` ink, on `--success-soft` when it sits on a tint. The soft pair is what the brand layer is checked to make readable (3:1 on the tint and on the page); the solid tone reads 3.8:1 or worse on white, so as a text colour it fails. The tones are the grammar's status tones (`success`, `warning`, `danger`, `info`), read from `lib/status-tones.generated.mjs`, which is generated from the grammar with the stylelint vocabulary.
6
-
7
- Every rule below is an error in `starciFeConfig`; none can be switched off or suppressed inline.
8
-
9
- ## `starci-fe/status-text-uses-soft-foreground`
10
-
11
- No class that paints text, an icon or a text decoration with a solid status tone: `text-<tone>`, `fill-<tone>`, `stroke-<tone>`, `decoration-<tone>` (with any variant, opacity or `!`), read from `className`/`class`, from `cn()`/`clsx()` arguments, conditionals, arrays, constants and `classes` entries.
12
-
13
- **Invalid** (`src/components/leaves/StatusText/index.tsx`)
14
-
15
- ```tsx
16
- <span className="text-success" />
17
- <svg className={cn("size-4", ok && "fill-danger")} />
18
- ```
19
-
20
- **Valid** (`src/components/leaves/StatusText/index.tsx`)
21
-
22
- ```tsx
23
- <span className="bg-success-soft text-success-soft-foreground" />
24
- <button className="bg-success text-success-foreground" />
25
- <div className="border-danger ring-2 ring-warning" />
26
- ```
27
-
28
- **Finding code:** `FE_STYLE_TOKEN_ONLY`
29
-
30
- **Why:** `<file>` colours text or an icon with a solid status tone (`<what>`, for example `text-success`). A solid tone is a background colour; used as a text colour it reads below 4.5:1 on the page background.
31
-
32
- **Fix:** Change to the soft pair: `text-<tone>-soft-foreground` (with `bg-<tone>-soft` if it sits on a light background); solid tones are used only with `bg-<tone>` and `text-<tone>-foreground`.