@ksmv/ui-checks 0.29.0 → 0.30.1

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.30.1 - 2026-10-30
+
+- **Sai junto com o `@ksmv/ui-react` 0.30.1, sem mudança nas regras:** os contratos continuam tema 3.12.0 e contraste 20.0.0. A correção do `Combobox` não muda nenhuma cor do contrato (ver o CHANGELOG do `@ksmv/ui-react`).
+
+## 0.30.0 - 2026-10-30
+
+- **A `Surface` arranja os filhos, como o `Card`** (#606). Em todos os tons, o arranjo dos filhos pela `className` (`flex`, `grid`, `gap-*`, `space-*`, `items-*`, `justify-*` e as propriedades de `style` equivalentes) passa a ser livre em `components/override`. O fundo, o padding e a borda continuam exigindo `data-ui-override`.
+- **Um arquivo de tema fora do `include` é erro de configuração** (#608). Quando um arquivo de `themes[].files` existe mas o `include` o deixa de fora, a saída é 2, com a mensagem que diz qual arquivo acrescentar. Antes, as declarações dele não eram lidas, e o tema aparecia como incompleto e os pares como sem cobertura, sem dizer por quê. Vale também para um tema com `computedEvidence`, porque a regra de forma e as declarações leem o arquivo. **Quem aponta o tema em `node_modules`** acrescenta o arquivo ao `include`.
+- **Spread de props escritas** (#608). Em `tokens/contrast`, um spread de objeto literal em JSX, ou da escolha entre dois (`{...(pronto ? { onBuscar } : {})}`), em que nenhuma prop é `className`, `class`, `style`, `dangerouslySetInnerHTML` ou de cor, passa a ficar coberto. Os outros spreads continuam sem cobertura.
+- **Contratos:** sem mudança, tema `3.12.0` e contraste `20.0.0`.
+
 ## 0.29.0 - 2026-10-28
 
 - **Contratos de tema 3.12.0 e contraste 20.0.0** empacotados.

package/README.md

@@ -45,7 +45,9 @@ export default defineConfig({
 
 O valor de `selector` deve ser **textualmente idêntico** ao seletor escrito no CSS, inclusive nas aspas. O verificador não tenta provar que grafias diferentes são equivalentes.
 
-`include` precisa encontrar arquivos: nenhum arquivo analisado é falha, não sucesso. `exclude` e `suppressions` são opcionais.
+`include` precisa encontrar arquivos: nenhum arquivo analisado é falha, não sucesso. `exclude` e `suppressions` são opcionais. Os arquivos de `themes[].files` são lidos como os outros do `include`. Por isso, um tema de fora da pasta do app, como `node_modules/@ksmv/ui-react/dist/themes/neutral.css`, também entra no `include`. Desde a 0.30.0, um arquivo de tema que existe mas fica fora do `include` é erro de configuração (saída 2), com a mensagem que diz qual arquivo acrescentar. Antes, o tema aparecia como incompleto e os pares como sem cobertura, sem dizer por quê. Vale também para um tema com `computedEvidence`: a regra de forma e as declarações continuam lendo o arquivo.
+
+Um spread em JSX (`{...props}`) fica sem cobertura em `tokens/contrast`, porque pode levar `className`, `style` ou uma cor que a regra não lê. Desde a 0.30.0, o spread de props escritas no código, seja um objeto literal ou a escolha entre dois (`{...(pronto ? { onBuscar } : {})}`), em que nenhuma é `className`, `class`, `style`, `dangerouslySetInnerHTML` ou uma propriedade de cor, fica coberto.
 
 ## Baseline
 
@@ -176,7 +178,7 @@ components: {
 ```
 
 - **Livre:** o que encaixa o componente no pai — margem, largura, item de flex/grid (`flex-1`, `self-*`, `col-span-*`…), posição, `z-*`, visibilidade (`hidden`, `sr-only`) e alinhamento do texto. No `style`, as propriedades equivalentes.
-- **Exige `data-ui-override="motivo"` no mesmo elemento:** aparência (cor, fundo, borda, raio, sombra, fonte, altura, padding, `gap-*`, `overflow-*`), arranjo interno (`flex`, `grid-cols-*`, `justify-*`, `items-*`, `block`) e qualquer classe fora do catálogo, inclusive classes próprias do produto. Exceção, desde a 0.24.0: o `Card` é um bloco cujos filhos o consumidor arranja pela `className`, como a casa, então nele o arranjo dos filhos é livre (`block`, `flex`, `grid`, `space-x-*`, `space-y-*`, `gap-*`, `flex-col`, `grid-cols-*`, `items-*`, `justify-*` e afins, e as propriedades de `style` equivalentes, com o `display` só nos valores de arranjo escritos no código: `block`, `flex`, `inline-flex`, `grid`, `inline-grid` e `flow-root`; `contents`, `none` ou um valor em variável exigem a marca); uma divisória entre os filhos (`divide-*`), um fundo ou um padding continuam exigindo a marca. Também exigem a marca `className` ou `style` que a regra não consegue ler e props repassadas depois de `className` ou `style`.
+- **Exige `data-ui-override="motivo"` no mesmo elemento:** aparência (cor, fundo, borda, raio, sombra, fonte, altura, padding, `gap-*`, `overflow-*`), arranjo interno (`flex`, `grid-cols-*`, `justify-*`, `items-*`, `block`) e qualquer classe fora do catálogo, inclusive classes próprias do produto. Exceção, desde a 0.24.0: o `Card` é um bloco cujos filhos o consumidor arranja pela `className`, como a casa, e desde a 0.30.0 a `Surface` também, em todos os tons. Então nos dois o arranjo dos filhos é livre (`block`, `flex`, `grid`, `space-x-*`, `space-y-*`, `gap-*`, `flex-col`, `grid-cols-*`, `items-*`, `justify-*` e afins, e as propriedades de `style` equivalentes, com o `display` só nos valores de arranjo escritos no código: `block`, `flex`, `inline-flex`, `grid`, `inline-grid` e `flow-root`; `contents`, `none` ou um valor em variável exigem a marca); uma divisória entre os filhos (`divide-*`), um fundo ou um padding continuam exigindo a marca. Também exigem a marca `className` ou `style` que a regra não consegue ler e props repassadas depois de `className` ou `style`.
 - **Relatório:** sem marca, é uma violação (saída 1), que pode entrar em baseline durante a migração. Com marca, o elemento aparece em `overrides`, com o motivo.
 - **Arquivos:** os do `components.include` recebem só esta regra. Um arquivo que também está no `include` principal recebe as duas coisas, e aí a cobertura dinâmica volta a valer nele.
 - **O que a regra não vê:** um componente do produto que repassa props para um componente da biblioteca, e CSS do produto que mira as classes internas `.ui-*`; props repassadas sozinhas ou antes de `className`/`style` (`<Button {...props} />`); componente usado como valor (`const X = Button; <X />`); arquivos que não compilam — aparecem como erro operacional de parse (saída 2) e não são analisados pela regra.

package/dist/rules/overrideCatalog.js

@@ -82,8 +82,11 @@ const arrangementUtilities = [
     /^(?:items|justify-items|place-items)-(?:start|end|center|baseline|stretch|normal)$/u,
     /^(?:justify|content|place-content)-(?:start|end|center|between|around|evenly|stretch|normal|baseline)$/u,
 ];
-// The library's components that arrange their children by the consumer's className.
-export const arrangingComponents = new Set(["Card"]);
+// The library's components that arrange their children by the consumer's
+// className: the Card, and since 0.30.0 the Surface in every tone, whose
+// panels and frames the apps lay out as the house does (a request of the
+// conselhos).
+export const arrangingComponents = new Set(["Card", "Surface"]);
 export function classifyClass(token, component) {
     const utility = utilityOf(token);
     if (freeUtilities.some((pattern) => pattern.test(utility)))

package/dist/rules/tokenContrast.js

@@ -1,4 +1,4 @@
-import { isComputedPropertyName, isIdentifier, isJsxAttribute, isJsxExpression, isObjectLiteralExpression, isPropertyAssignment, isJsxSpreadAttribute, isStringLiteralLikeNode, } from "typescript/unstable/ast";
+import { isComputedPropertyName, isConditionalExpression, isIdentifier, isJsxAttribute, isJsxExpression, isObjectLiteralExpression, isPropertyAssignment, isJsxSpreadAttribute, isParenthesizedExpression, isShorthandPropertyAssignment, isStringLiteralLikeNode, } from "typescript/unstable/ast";
 import { composite, contrastRatio, faded, isColorBearingProperty, mix, paintOver, resolveColor, } from "../color.js";
 import { parseContrastManifest, } from "../contracts.js";
 import { createThemeCollector } from "./theme.js";
@@ -89,6 +89,28 @@ function propertyName(node) {
         ? node.expression.text
         : undefined;
 }
+// A spread whose props are written out in the source, as an object literal or
+// a choice between two (`{...(ready ? { onSearch } : {})}`), and none of them
+// carries a style: nothing in it can paint (a request of the login, 0.30.0).
+// Any other spread, or one that may pass className, style or a color, still
+// needs computed coverage; class too, which a custom element, or a component
+// that passes it on, renders, and dangerouslySetInnerHTML, whose markup may
+// carry its own classes and colors.
+const styleProps = new Set(["className", "class", "style", "dangerouslySetInnerHTML"]);
+function spreadsNoStyle(node) {
+    if (isParenthesizedExpression(node))
+        return spreadsNoStyle(node.expression);
+    if (isConditionalExpression(node))
+        return spreadsNoStyle(node.whenTrue) && spreadsNoStyle(node.whenFalse);
+    if (!isObjectLiteralExpression(node))
+        return false;
+    return node.properties.every((property) => {
+        if (!isPropertyAssignment(property) && !isShorthandPropertyAssignment(property))
+            return false;
+        const name = propertyName(property.name);
+        return name !== undefined && !styleProps.has(name) && !isColorBearingProperty(name);
+    });
+}
 function dynamicStyleResult(file) {
     const result = { uncovered: [], violations: [] };
     if (!file.sourceFile) {
@@ -96,7 +118,7 @@ function dynamicStyleResult(file) {
     }
     const sourceFile = file.sourceFile;
     const visit = (node) => {
-        if (isJsxSpreadAttribute(node)) {
+        if (isJsxSpreadAttribute(node) && !spreadsNoStyle(node.expression)) {
             const position = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
             result.uncovered.push({
                 column: position.character + 1,

package/dist/scan.js

@@ -1,4 +1,4 @@
-import { glob, readFile as readFileFromDisk } from "node:fs/promises";
+import { glob, readFile as readFileFromDisk, stat } from "node:fs/promises";
 import { extname, relative, resolve } from "node:path";
 import postcss from "postcss";
 import { computeLineStarts, createScanner, LanguageVariant, SyntaxKind, } from "typescript/unstable/ast";
@@ -290,6 +290,26 @@ export async function runChecks(config, options = {}) {
     }))
         .sort((left, right) => left.path.localeCompare(right.path));
     report.filesDiscovered = includedBeforeExcludes.length;
+    // A theme's files are read as any other file of include: one that exists
+    // but include leaves out would report the theme as incomplete and every pair
+    // unresolved, with nothing saying why (measured by the login, 0.30.0). With
+    // computed evidence too: the shape rule and the declarations read the file.
+    for (const theme of config.themes ?? []) {
+        for (const file of theme.files) {
+            const absolute = resolve(root, file);
+            if (selected.has(absolute))
+                continue;
+            const exists = await stat(absolute).then((found) => found.isFile(), () => false);
+            if (!exists)
+                continue;
+            report.operationalErrors.push({
+                code: "config",
+                message: includedBeforeExcludes.includes(absolute)
+                    ? `Theme ${theme.name} file ${toPosixPath(relative(root, absolute))} is removed by exclude: its declarations are not read. Take it out of exclude.`
+                    : `Theme ${theme.name} file ${toPosixPath(relative(root, absolute))} is not matched by include: its declarations are not read. Add it to include.`,
+            });
+        }
+    }
     const componentPaths = config.components
         ? (await discoverFiles(root, config.components.include, config.components.exclude)).filter((path) => extname(path).toLowerCase() !== ".css")
         : [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ksmv/ui-checks",
-  "version": "0.29.0",
+  "version": "0.30.1",
   "description": "Static and computed quality checks for semantic UI token contracts.",
   "keywords": ["accessibility", "design-tokens", "quality", "static-analysis"],
   "license": "Apache-2.0",