@ksmv/ui-checks 0.30.0 → 0.31.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.31.0 - 2026-10-31
+
+- **Regra opcional `components/native-date`** (#634). `components.nativeDates: true` recusa `type="date"` e `type="datetime-local"` literais em JSX. Fica desligada por padrão, até cada app ligar.
+- **A altura é livre na `Surface`** (#629). `h-*` e `height` não exigem mais `data-ui-override` nela, e só nela.
+- **Tema com barra invertida em POSIX** (#632). Um arquivo de tema escrito com `\` agora passa pelo diagnóstico do `include`.
+- **Contratos:** sem mudança, tema `3.12.0` e contraste `20.0.0`.
+
+## 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`.

package/README.md

@@ -178,9 +178,11 @@ 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, 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`.
+- **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. Na `Surface`, desde a 0.31.0, a altura é livre (`h-*` e `height`), para um painel ou uma moldura que ocupa o espaço. 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.
+
+Desde a 0.31.0, `components.nativeDates: true` liga a regra opcional `components/native-date`, desligada por padrão: ela recusa um `type="date"` ou `type="datetime-local"` escrito literalmente em JSX, em maiúsculas ou minúsculas, inclusive num spread de objeto literal, em `input` ou numa peça, porque o campo nativo segue o idioma da máquina. Use `DateInput` e, para texto, os formatadores. Um `type` vindo de variável não é lido.
 - **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.
 
 ### Detalhes

package/dist/config.d.ts

@@ -14,6 +14,8 @@ export interface ComponentsConfig {
     classHelpers?: string[];
     exclude?: string[];
     include: string[];
+    /** Refuses the native date fields, with a literal type="date" or "datetime-local"; off by default (0.31.0). */
+    nativeDates?: boolean;
     sources?: string[];
 }
 export interface ChecksConfig {

package/dist/rules/componentOverride.d.ts

@@ -1,6 +1,10 @@
+import { type Node } from "typescript/unstable/ast";
 import type { CheckRule } from "../scan.js";
 export interface ComponentOverrideOptions {
     classHelpers?: string[];
     sources?: string[];
 }
+export declare function propertyKey(node: Node): string | undefined;
+/** Unwraps type assertions, `satisfies` and `!` before reading an expression. */
+export declare function unwrapTypeWrappers(node: Node): Node;
 export declare function createComponentOverrideRule({ classHelpers, sources, }?: ComponentOverrideOptions): CheckRule;

package/dist/rules/componentOverride.js

@@ -79,7 +79,7 @@ function tagParts(tagName) {
     }
     return isIdentifier(current) ? { path, root: current.text } : undefined;
 }
-function propertyKey(node) {
+export function propertyKey(node) {
     if (isIdentifier(node) || isStringLiteralLikeNode(node))
         return node.text;
     return isComputedPropertyName(node) && isStringLiteralLikeNode(node.expression)
@@ -87,7 +87,7 @@ function propertyKey(node) {
         : undefined;
 }
 /** Unwraps type assertions, `satisfies` and `!` before reading an expression. */
-function unwrapTypeWrappers(node) {
+export function unwrapTypeWrappers(node) {
     let current = node;
     while (isParenthesizedExpression(current) ||
         isAsExpression(current) ||

package/dist/rules/default.js

@@ -1,4 +1,5 @@
 import { createComponentOverrideRule } from "./componentOverride.js";
+import { createNativeDateRule } from "./nativeDate.js";
 import { createNoLiteralColorRule } from "./noLiteralColor.js";
 import { createTokenCompleteRule, loadThemeContract } from "./tokenComplete.js";
 import { createTokenContrastRule, loadContrastManifest, } from "./tokenContrast.js";
@@ -24,5 +25,6 @@ export async function createDefaultRules({ components, computed, contract, manif
         ...(components
             ? [createComponentOverrideRule({ classHelpers: components.classHelpers, sources: components.sources })]
             : []),
+        ...(components?.nativeDates ? [createNativeDateRule()] : []),
     ];
 }

package/dist/rules/nativeDate.d.ts

@@ -0,0 +1,2 @@
+import type { CheckRule } from "../scan.js";
+export declare function createNativeDateRule(): CheckRule;

package/dist/rules/nativeDate.js

@@ -0,0 +1,59 @@
+import { isJsxAttribute, isJsxExpression, isJsxOpeningElement, isJsxSelfClosingElement, isJsxSpreadAttribute, isObjectLiteralExpression, isPropertyAssignment, isStringLiteralLikeNode, } from "typescript/unstable/ast";
+import { propertyKey, unwrapTypeWrappers } from "./componentOverride.js";
+const nativeDateTypes = new Set(["date", "datetime-local"]);
+function literalOf(initializer) {
+    const expression = initializer && isJsxExpression(initializer) ? initializer.expression : initializer;
+    const written = expression && unwrapTypeWrappers(expression);
+    return written && isStringLiteralLikeNode(written) ? written.text : undefined;
+}
+// The native date fields follow the machine's language, so the same screen
+// shows mm/dd on one and dd/mm on another: the house's are DateInput, and the
+// formatters for text. Optional, since an app turns it on when its fields have
+// moved (0.31.0). Only a literal type is read, in any case, as HTML reads it,
+// and a literal spread with it: a type from a variable is the app's own field.
+export function createNativeDateRule() {
+    return {
+        name: "components/native-date",
+        scope: "components",
+        check(file) {
+            const result = { uncovered: [], violations: [] };
+            const sourceFile = file.sourceFile;
+            if (!sourceFile)
+                return result;
+            const typeOf = (attribute) => {
+                if (isJsxAttribute(attribute)) {
+                    return attribute.name.getText(sourceFile) === "type" ? literalOf(attribute.initializer) : undefined;
+                }
+                if (!isJsxSpreadAttribute(attribute) || !isObjectLiteralExpression(attribute.expression))
+                    return undefined;
+                // The last key is the one that holds.
+                const property = [...attribute.expression.properties]
+                    .reverse()
+                    .find((entry) => isPropertyAssignment(entry) && propertyKey(entry.name) === "type");
+                return property && isPropertyAssignment(property) ? literalOf(property.initializer) : undefined;
+            };
+            const visit = (node) => {
+                if (isJsxOpeningElement(node) || isJsxSelfClosingElement(node)) {
+                    for (const attribute of node.attributes.properties) {
+                        const type = typeOf(attribute)?.toLowerCase();
+                        if (type === undefined || !nativeDateTypes.has(type))
+                            continue;
+                        const position = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+                        result.violations.push({
+                            anchor: `${node.tagName.getText(sourceFile)}|${type}`,
+                            column: position.character + 1,
+                            line: position.line + 1,
+                            message: `${node.tagName.getText(sourceFile)} has the native type "${type}": use DateInput from @ksmv/ui-react, which shows dd/mm/aaaa on every machine.`,
+                            nodeKind: "native-date",
+                            path: file.path,
+                            rule: "components/native-date",
+                        });
+                    }
+                }
+                node.forEachChild(visit);
+            };
+            visit(sourceFile);
+            return result;
+        },
+    };
+}

package/dist/rules/overrideCatalog.js

@@ -87,10 +87,15 @@ const arrangementUtilities = [
 // panels and frames the apps lay out as the house does (a request of the
 // conselhos).
 export const arrangingComponents = new Set(["Card", "Surface"]);
+// The Surface's own height, for a panel or a frame that fills its room
+// (0.31.0, a request of the conselhos).
+const surfaceHeight = new RegExp(`^h-(?:${num}|${frac}|px|auto|full|screen|svh|lvh|dvh|min|max|fit|${arb})$`, "u");
 export function classifyClass(token, component) {
     const utility = utilityOf(token);
     if (freeUtilities.some((pattern) => pattern.test(utility)))
         return "free";
+    if (component === "Surface" && surfaceHeight.test(utility))
+        return "free";
     if (component !== undefined && arrangingComponents.has(component) && arrangementUtilities.some((pattern) => pattern.test(utility)))
         return "free";
     return "visual";
@@ -120,6 +125,8 @@ export function classifyStyleProperty(name, component, value) {
     const camel = name.replace(/-([a-z])/gu, (_, letter) => letter.toUpperCase());
     if (freeStyleProperties.has(camel))
         return "free";
+    if (component === "Surface" && camel === "height")
+        return "free";
     if (component !== undefined && arrangingComponents.has(component) && arrangementStyleProperties.has(camel)) {
         if (camel === "display" && !(value !== undefined && arrangementDisplays.has(value.trim())))
             return "visual";

package/dist/scan.js

@@ -172,15 +172,17 @@ function validateRuntimeConfig(value) {
         if (!components ||
             typeof components !== "object" ||
             Array.isArray(components) ||
-            Object.keys(components).some((key) => !["classHelpers", "exclude", "include", "sources"].includes(key)) ||
+            Object.keys(components).some((key) => !["classHelpers", "exclude", "include", "nativeDates", "sources"].includes(key)) ||
             !isList(components.include, true) ||
             (components.exclude !== undefined &&
                 !isList(components.exclude, false)) ||
             (components.sources !== undefined &&
                 !isList(components.sources, true)) ||
+            (components.nativeDates !== undefined &&
+                typeof components.nativeDates !== "boolean") ||
             (components.classHelpers !== undefined &&
                 !isList(components.classHelpers, false))) {
-            return "components needs include patterns and optional exclude, sources and classHelpers string lists.";
+            return "components needs include patterns, optional exclude, sources and classHelpers string lists, and an optional nativeDates boolean.";
         }
     }
     return undefined;
@@ -296,7 +298,7 @@ export async function runChecks(config, options = {}) {
     // 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);
+            const absolute = resolve(root, toPosixPath(file));
             if (selected.has(absolute))
                 continue;
             const exists = await stat(absolute).then((found) => found.isFile(), () => false);

package/package.json

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