@estiva-app/ui 0.43.0 → 0.44.1

package/src/gates/token-joined.ts

@@ -0,0 +1,94 @@
+/**
+ * The token contract, read inside a class list joined by hand (UIG-42):
+ *
+ *   <div className={['text-sm', open && 'bg-gray-100'].join(' ')} />
+ *
+ * The Tailwind plugin stops at a function call, so it never reads the list in
+ * front of `.join(' ')`, and no setting can make it: a call it is told about is
+ * read at its arguments, which here is the `' '`. This rule reads the list and
+ * tests each class against the same patterns, with the same messages, as the
+ * rule it stands in for. It registers once per rule it mirrors, so an error
+ * stays an error and a warning a warning (`token-joined/classes`, `/values`,
+ * `/spacing`).
+ *
+ * A list joined with anything but one space is not a class list, and a
+ * sentence built this way passes unless one of its words is itself such a
+ * class, as in `'set text-sm here'`. Only strings written in the list are
+ * read, directly or behind `cond && …`, `a ? … : …` and a template's fixed
+ * parts; a list worked out while it runs cannot be read.
+ */
+import type { ESLint, Rule } from 'eslint'
+
+/** One pattern and its message, the shape `no-restricted-classes` takes. `$0` is the class. */
+export interface Restriction {
+  pattern: string
+  message: string
+}
+
+interface Node {
+  type: string
+  [key: string]: unknown
+}
+
+const isOneSpace = (node: Node | undefined) => node?.type === 'Literal' && node.value === ' '
+
+/** `.join` on a list, through any `.filter(…)` between them. */
+function joinedList(call: Node): Node | undefined {
+  const callee = call.callee as Node
+  if (callee.type !== 'MemberExpression' || callee.computed || (callee.property as Node).name !== 'join') return undefined
+  if ((call.arguments as Node[]).length !== 1 || !isOneSpace((call.arguments as Node[])[0])) return undefined
+  let list = callee.object as Node
+  while (list.type === 'CallExpression' && (list.callee as Node).type === 'MemberExpression' && ((list.callee as Node).property as Node).name === 'filter') {
+    list = (list.callee as Node).object as Node
+  }
+  return list.type === 'ArrayExpression' ? list : undefined
+}
+
+/** The strings written in one item of the list, each with the node an escape sits above. */
+function stringsIn(node: Node | null, out: { node: Node; text: string }[] = []) {
+  if (!node) return out
+  if (node.type === 'Literal' && typeof node.value === 'string') out.push({ node, text: node.value })
+  else if (node.type === 'TemplateLiteral') for (const quasi of node.quasis as Node[]) out.push({ node: quasi, text: String((quasi.value as { cooked: string }).cooked ?? '') })
+  else if (node.type === 'ConditionalExpression') stringsIn(node.consequent as Node, out), stringsIn(node.alternate as Node, out)
+  else if (node.type === 'LogicalExpression') {
+    if (node.operator !== '&&') stringsIn(node.left as Node, out)
+    stringsIn(node.right as Node, out)
+  } else if (node.type === 'TSAsExpression' || node.type === 'TSSatisfiesExpression') stringsIn(node.expression as Node, out)
+  return out
+}
+
+const joinedListRule: Rule.RuleModule = {
+  meta: {
+    type: 'problem',
+    docs: { description: 'The token contract, inside a class list joined with .join(" ")' },
+    schema: [
+      {
+        type: 'object',
+        properties: { restrict: { type: 'array', items: { type: 'object', properties: { pattern: { type: 'string' }, message: { type: 'string' } }, required: ['pattern', 'message'] } } },
+        required: ['restrict'],
+        additionalProperties: false,
+      },
+    ],
+  },
+  create(context) {
+    const { restrict } = context.options[0] as { restrict: Restriction[] }
+    const rules = restrict.map(({ pattern, message }) => ({ pattern: new RegExp(pattern), message }))
+    return {
+      CallExpression(ruleNode: Rule.Node) {
+        const list = joinedList(ruleNode as unknown as Node)
+        if (!list) return
+        for (const item of list.elements as (Node | null)[]) {
+          for (const { node, text } of stringsIn(item)) {
+            for (const name of text.split(/\s+/)) {
+              const rule = name && rules.find(({ pattern }) => pattern.test(name))
+              if (rule) context.report({ node: node as unknown as Rule.Node, message: rule.message.replaceAll('$0', name) })
+            }
+          }
+        }
+      },
+    }
+  },
+}
+
+/** The plugin, as the token lint registers it: one rule, under three names. */
+export const tokenJoinedPlugin: ESLint.Plugin = { rules: { classes: joinedListRule, values: joinedListRule, spacing: joinedListRule } }

package/src/gates/token-lint.ts

@@ -28,6 +28,8 @@
  * Where the plugin looks: every `className`, every `cn()` / `clsx()` argument,
  * and the values of a class map whose name ends in `Styles` / `_STYLES` or
  * `Classes` / `_CLASSES`. A class map named any other way is invisible to it.
+ * A class list joined by hand, `[…].join(' ')`, is read by `token-joined`
+ * (`./token-joined.ts`, UIG-42) with the same patterns.
  *
  * Tests are out of `tokenValues` (ruling of 13 September): a test mounts markup
  * to test it. A kept hand-written value says why:
@@ -39,6 +41,7 @@ import type { ESLint, Linter } from 'eslint'
 import betterTailwindcss from 'eslint-plugin-better-tailwindcss'
 import { getDefaultSelectors } from 'eslint-plugin-better-tailwindcss/defaults'
 import { parser as typescriptParser, plugin as typescriptPlugin } from 'typescript-eslint'
+import { type Restriction, tokenJoinedPlugin } from './token-joined'
 import { INLINE_STYLE_MESSAGE, INLINE_STYLE_TOKEN_KEYS, tokenStylePlugin } from './token-style'
 
 /** Who reads the messages. */
@@ -104,19 +107,39 @@ const WORDS = {
   },
 } satisfies Record<TokenAudience, Record<string, string>>
 
+/**
+ * The variants in front of a class, arbitrary ones too (`[&_pre]:`,
+ * `data-[state=open]:`, `group-hover/row:`), and the `!` that makes a class
+ * important. Until UIG-42 the four class rules read only plain variants, so
+ * `[&_pre]:text-sm` and `group-hover/row:bg-gray-100` passed.
+ */
+const V = '^(?:(?:[^:\\[\\]\\s]|\\[[^\\]]*\\])+:)*!?'
+
 /**
  * The class rules. `no-unknown-classes` reads the app's own Tailwind config, so
  * it knows exactly what the preset and the app generate.
  */
 export function tokenLint({ tailwindConfig = 'tailwind.config.js', audience = 'app' }: TokenLintOptions = {}): Linter.Config {
   const words = WORDS[audience]
+  const restrict: Restriction[] = [
+    { pattern: `${V}text-(?:xs|sm|base|lg|xl|[2-9]xl)$`, message: words.ramp },
+    {
+      pattern: `${V}(?:text|bg|border|ring|outline|fill|stroke|decoration|divide|placeholder|from|via|to|accent|caret|shadow)-(?:black|white|slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)(?:-[0-9]{2,3})?(?:/[0-9]{1,3})?$`,
+      message: words.palette,
+    },
+    { pattern: `${V}[a-z-]+-\\[[^\\]]*(?:#[0-9a-fA-F]{3}|rgba?\\(|hsla?\\(|oklch\\()`, message: words.raw },
+    {
+      pattern: `${V}(?:text|bg|border|ring|outline|fill|stroke|decoration|divide|placeholder|from|via|to|accent|caret|shadow)-(?:bg|text|border|accent|info|warning|success|error)-[a-z-]+/[0-9]{1,3}$`,
+      message: words.opacity,
+    },
+  ]
   return {
     files: ['**/*.{ts,tsx}'],
     languageOptions: {
       parser: typescriptParser,
       parserOptions: { ecmaFeatures: { jsx: true } },
     },
-    plugins: { 'better-tailwindcss': betterTailwindcss },
+    plugins: { 'better-tailwindcss': betterTailwindcss, 'token-joined': tokenJoinedPlugin },
     settings: {
       'better-tailwindcss': {
         tailwindConfig,
@@ -125,24 +148,9 @@ export function tokenLint({ tailwindConfig = 'tailwind.config.js', audience = 'a
     },
     rules: {
       'better-tailwindcss/no-unknown-classes': 'error',
-      'better-tailwindcss/no-restricted-classes': [
-        'error',
-        {
-          restrict: [
-            { pattern: '^(?:[a-z0-9-]+:)*text-(?:xs|sm|base|lg|xl|[2-9]xl)$', message: words.ramp },
-            {
-              pattern:
-                '^(?:[a-z0-9-]+:)*(?:text|bg|border|ring|outline|fill|stroke|decoration|divide|placeholder|from|via|to|accent|caret|shadow)-(?:black|white|slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)(?:-[0-9]{2,3})?(?:/[0-9]{1,3})?$',
-              message: words.palette,
-            },
-            { pattern: '^(?:[a-z0-9-]+:)*[a-z-]+-\\[[^\\]]*(?:#[0-9a-fA-F]{3}|rgba?\\(|hsla?\\(|oklch\\()', message: words.raw },
-            {
-              pattern: '^(?:[a-z0-9-]+:)*(?:text|bg|border|ring|outline|fill|stroke|decoration|divide|placeholder|from|via|to|accent|caret|shadow)-(?:bg|text|border|accent|info|warning|success|error)-[a-z-]+/[0-9]{1,3}$',
-              message: words.opacity,
-            },
-          ],
-        },
-      ],
+      'better-tailwindcss/no-restricted-classes': ['error', { restrict }],
+      // A class list joined by hand, which the plugin above cannot read (UIG-42).
+      'token-joined/classes': ['error', { restrict }],
       // UIG-21: "use the package's cn(), never a plain twMerge" was a sentence
       // in all three repos' CLAUDE.md, and nothing checked it.
       'no-restricted-imports': ['error', { paths: [{ name: 'tailwind-merge', message: words.merge }] }],
@@ -150,10 +158,8 @@ export function tokenLint({ tailwindConfig = 'tailwind.config.js', audience = 'a
   }
 }
 
-// UIG-28's patterns. The variant part reads arbitrary variants too
-// (`[&_pre]:`, `data-[state]:`, `group-hover/row:`). A colour inside `text-[…]`
-// is left to the raw-colour rule of `tokenLint`.
-const V = '^(?:(?:[^:\\[\\]\\s]|\\[[^\\]]*\\])+:)*!?'
+// UIG-28's patterns. A colour inside `text-[…]` is left to the raw-colour rule
+// of `tokenLint`.
 const NOT_COLOUR = '(?!color:|#|rgba?\\(|hsla?\\(|oklch\\(|var\\()'
 const HAND_WRITTEN = {
   type: `${V}(?:text-\\[${NOT_COLOUR}|text-\\[length:|leading-\\[|tracking-\\[)[^\\]]+\\](?:/\\S*)?$`,
@@ -201,55 +207,51 @@ export function tokenValues({ audience = 'app' }: Pick<TokenLintOptions, 'audien
   const cornersBySize: Record<string, string[]> = {}
   for (const [name, size] of Object.entries(preset.theme.extend.borderRadius)) (cornersBySize[size] ??= []).push(name === 'DEFAULT' ? 'rounded' : `rounded-${name}`)
 
+  const values: Restriction[] = [
+    ...Object.entries(tokensBySize).map(([size, names]) => ({
+      pattern: `${V}text-\\[${size.replace('.', '\\.')}\\](?:/\\S*)?$`,
+      message: `$0 is the type ramp written by hand. Use ${names.join(' or ')}.`,
+    })),
+    {
+      pattern: HAND_WRITTEN.type,
+      message: words.type,
+    },
+    ...Object.entries(cornersBySize).map(([size, names]) => ({
+      pattern: `${V}rounded(?:-(?:t|r|b|l|s|e|tl|tr|br|bl|ss|se|es|ee))?-\\[${size.replace('.', '\\.')}\\]$`,
+      message: `$0 is a corner written by hand. Use ${names.join(' or ')} (with the same side, if it has one).`,
+    })),
+    {
+      pattern: HAND_WRITTEN.corner,
+      message: words.corner,
+    },
+    {
+      pattern: HAND_WRITTEN.shadow,
+      message: words.shadow,
+    },
+  ]
+  const spacing: Restriction[] = [
+    {
+      pattern: HAND_WRITTEN.spacing,
+      message: '$0 is a size or a space written by hand. Use a step of the spacing scale (p-3, h-9, gap-2...) if one fits. Reported, not blocked.',
+    },
+    {
+      pattern: HAND_WRITTEN.width,
+      message: '$0 is a border or ring width written by hand. Use border, border-2, ring-1... if one fits. Reported, not blocked.',
+    },
+  ]
+
   return {
     files: ['**/*.{ts,tsx}'],
     ignores: ['**/*.test.ts', '**/*.test.tsx'],
-    plugins: { 'token-values': betterTailwindcss, 'token-spacing': betterTailwindcss, 'token-style': tokenStylePlugin },
+    plugins: { 'token-values': betterTailwindcss, 'token-spacing': betterTailwindcss, 'token-style': tokenStylePlugin, 'token-joined': tokenJoinedPlugin },
     rules: {
       // A style kept in a const and passed by name (R9): the selector below cannot follow it.
       'token-style/no-token-style': 'error',
-      'token-values/no-restricted-classes': [
-        'error',
-        {
-          restrict: [
-            ...Object.entries(tokensBySize).map(([size, names]) => ({
-              pattern: `${V}text-\\[${size.replace('.', '\\.')}\\](?:/\\S*)?$`,
-              message: `$0 is the type ramp written by hand. Use ${names.join(' or ')}.`,
-            })),
-            {
-              pattern: HAND_WRITTEN.type,
-              message: words.type,
-            },
-            ...Object.entries(cornersBySize).map(([size, names]) => ({
-              pattern: `${V}rounded(?:-(?:t|r|b|l|s|e|tl|tr|br|bl|ss|se|es|ee))?-\\[${size.replace('.', '\\.')}\\]$`,
-              message: `$0 is a corner written by hand. Use ${names.join(' or ')} (with the same side, if it has one).`,
-            })),
-            {
-              pattern: HAND_WRITTEN.corner,
-              message: words.corner,
-            },
-            {
-              pattern: HAND_WRITTEN.shadow,
-              message: words.shadow,
-            },
-          ],
-        },
-      ],
-      'token-spacing/no-restricted-classes': [
-        'warn',
-        {
-          restrict: [
-            {
-              pattern: HAND_WRITTEN.spacing,
-              message: '$0 is a size or a space written by hand. Use a step of the spacing scale (p-3, h-9, gap-2...) if one fits. Reported, not blocked.',
-            },
-            {
-              pattern: HAND_WRITTEN.width,
-              message: '$0 is a border or ring width written by hand. Use border, border-2, ring-1... if one fits. Reported, not blocked.',
-            },
-          ],
-        },
-      ],
+      'token-values/no-restricted-classes': ['error', { restrict: values }],
+      'token-spacing/no-restricted-classes': ['warn', { restrict: spacing }],
+      // The same two inside a class list joined by hand (UIG-42).
+      'token-joined/values': ['error', { restrict: values }],
+      'token-joined/spacing': ['warn', { restrict: spacing }],
       'no-restricted-syntax': [
         'error',
         {