praxis-kit 4.1.3 → 5.0.0

package/dist/svelte/index.js

@@ -1760,17 +1760,22 @@ var RuleValidator = class _RuleValidator extends InvariantBase {
 };
 
 // ../../lib/contract/src/children/children-evaluator.ts
+var isTextLike = (child) => isString(child) || isNumber(child);
 var ChildrenEvaluator = class extends InvariantBase {
   #context;
   #rules;
   #ruleNames;
   #matcher;
   #ruleValidator;
-  constructor(rules, diagnostics, context = "Component") {
+  #exclusiveChildren;
+  #allowText;
+  constructor(rules, diagnostics, context = "Component", options = {}) {
     super(diagnostics);
     this.#context = context;
     this.#rules = rules.map((r) => normalizeChildRule(r));
     this.#ruleNames = this.#rules.map((r) => r.name);
+    this.#exclusiveChildren = options.exclusiveChildren ?? false;
+    this.#allowText = options.allowText ?? true;
     iterate.forEach(this.#rules, (rule) => {
       const { name, position, cardinality } = rule;
       if ((position === "first" || position === "last") && (cardinality.kind === "unbounded" || cardinality.max > 1)) {
@@ -1784,8 +1789,17 @@ var ChildrenEvaluator = class extends InvariantBase {
   }
   evaluate(children) {
     if (!this.active) return;
-    const { matrix, unexpectedIndices, ambiguousIndices } = this.#matcher.match(children);
+    const {
+      matrix,
+      unexpectedIndices: rawUnexpectedIndices,
+      ambiguousIndices
+    } = this.#matcher.match(children);
     this.#ruleValidator.validate(this.#rules, matrix, children.length);
+    const unexpectedIndices = new Set(
+      [...rawUnexpectedIndices].filter(
+        (ci) => isTextLike(children[ci]) ? this.#allowText === false : this.#exclusiveChildren
+      )
+    );
     if (unexpectedIndices.size === 0 && ambiguousIndices.size === 0) return;
     const violating = [...unexpectedIndices, ...ambiguousIndices].sort((a, b) => a - b);
     iterate.forEach(violating, (ci) => {
@@ -1907,8 +1921,11 @@ function metadata(name = "metadata") {
 function firstOptional(name, tag) {
   return { name, match: isTag(tag), cardinality: { max: 1 }, position: "first" };
 }
-function contract(children) {
-  return { diagnostics: warnDiagnostics, children };
+function contract(children, options) {
+  return { diagnostics: warnDiagnostics, children, ...options };
+}
+function closedContract(children) {
+  return contract(children, { exclusiveChildren: true });
 }
 function ariaContract(aria) {
   return { diagnostics: warnDiagnostics, aria };
@@ -1934,8 +1951,10 @@ var VOID_TAGS = [
 ];
 var TEXT_ONLY_TAGS = ["option", "script", "style", "textarea", "title"];
 var LANDMARK_TAGS = ["article", "aside", "footer", "header", "main", "nav"];
-var listContract = contract([{ name: "list-item", match: isTag("li", ...METADATA_TAGS) }]);
-var tableContract = contract([
+var listContract = closedContract([
+  { name: "list-item", match: isTag("li", ...METADATA_TAGS) }
+]);
+var tableContract = closedContract([
   firstOptional("caption", "caption"),
   { name: "colgroup", match: isTag("colgroup") },
   { name: "thead", match: isTag("thead"), cardinality: { max: 1 } },
@@ -1943,29 +1962,31 @@ var tableContract = contract([
   { name: "tfoot", match: isTag("tfoot"), cardinality: { max: 1 } },
   { name: "table-row", match: isTag("tr", ...METADATA_TAGS) }
 ]);
-var tableBodyContract = contract([
+var tableBodyContract = closedContract([
   { name: "table-row", match: isTag("tr", ...METADATA_TAGS) }
 ]);
-var tableRowContract = contract([
+var tableRowContract = closedContract([
   { name: "table-cell", match: isTag("td", "th", ...METADATA_TAGS) }
 ]);
-var colgroupContract = contract([{ name: "column", match: isTag("col", "template") }]);
-var dlContract = contract([
+var colgroupContract = closedContract([
+  { name: "column", match: isTag("col", "template") }
+]);
+var dlContract = closedContract([
   { name: "term", match: isTag("dt") },
   { name: "description", match: isTag("dd") },
   { name: "group", match: isTag("div") },
   metadata()
 ]);
-var selectContract = contract([
+var selectContract = closedContract([
   { name: "option", match: isTag("option", "optgroup", "hr", ...METADATA_TAGS) }
 ]);
-var optgroupContract = contract([
+var optgroupContract = closedContract([
   { name: "option", match: isTag("option", ...METADATA_TAGS) }
 ]);
-var datalistContract = contract([
+var datalistContract = closedContract([
   { name: "option", match: isTag("option", ...METADATA_TAGS) }
 ]);
-var pictureContract = contract([
+var pictureContract = closedContract([
   { name: "source", match: isTag("source", ...METADATA_TAGS) },
   { name: "image", match: isTag("img"), cardinality: { min: 1, max: 1 }, position: "last" }
 ]);
@@ -1981,23 +2002,18 @@ var mediaContract = contract([
   metadata(),
   { name: "content", match: isOpenContent("source", "track", ...METADATA_TAGS) }
 ]);
-var headContract = contract([
+var headContract = closedContract([
   {
     name: "metadata",
     match: isTag("base", "link", "meta", "noscript", "script", "style", "template", "title")
   }
 ]);
-var htmlContract = contract([
+var htmlContract = closedContract([
   { name: "head", match: isTag("head"), cardinality: { min: 1, max: 1 }, position: "first" },
   { name: "body", match: isTag("body"), cardinality: { min: 1, max: 1 } }
 ]);
-var voidContract = contract([]);
-var textOnlyContract = contract([
-  {
-    name: "text",
-    match: (child) => isString(child) || isNumber(child)
-  }
-]);
+var voidContract = contract([], { exclusiveChildren: true, allowText: false });
+var textOnlyContract = contract([], { exclusiveChildren: true });
 var landmarkContract = ariaContract([landmarkRoleRule, landmarkNameAdvisory]);
 var dialogContract = ariaContract([requireAccessibleName]);
 var menuContract = ariaContract([requireAccessibleName]);
@@ -2042,9 +2058,15 @@ var htmlContracts = {
 var htmlDiagnostics = warnDiagnostics2;
 function buildEvaluatorMap() {
   const map2 = /* @__PURE__ */ new Map();
-  iterate.forEachEntry(htmlContracts, (tag, { children }) => {
-    if (children?.length) {
-      map2.set(tag, new ChildrenEvaluator(children, htmlDiagnostics, `<${tag}>`));
+  iterate.forEachEntry(htmlContracts, (tag, { children, exclusiveChildren, allowText }) => {
+    if (children?.length || exclusiveChildren || allowText === false) {
+      map2.set(
+        tag,
+        new ChildrenEvaluator(children ?? [], htmlDiagnostics, `<${tag}>`, {
+          exclusiveChildren,
+          allowText
+        })
+      );
     }
   });
   return map2;
@@ -2255,7 +2277,7 @@ function definePipeline(factory) {
 }
 
 // ../core/src/options/resolve-factory-options.ts
-import { silentDiagnostics } from "../_shared/diagnostics.js";
+import { resolveDiagnostics, silentDiagnostics } from "../_shared/diagnostics.js";
 var EMPTY_VARIANT_KEYS = /* @__PURE__ */ new Set();
 function composeNormalizers(normalizers, fn) {
   if (!normalizers?.length) return fn;
@@ -2276,7 +2298,7 @@ function resolveFactoryOptions(options = {}) {
   const variantKeys = styling?.variants === void 0 ? EMPTY_VARIANT_KEYS : new Set(Object.keys(styling.variants));
   return Object.freeze({
     defaultTag: options.tag ?? "div",
-    diagnostics: enforcement?.diagnostics ?? silentDiagnostics,
+    diagnostics: resolveDiagnostics(enforcement?.diagnostics, silentDiagnostics),
     variantKeys,
     ...whenDefined("displayName", options.name),
     ...whenDefined("defaultProps", options.defaults),
@@ -2289,6 +2311,8 @@ function resolveFactoryOptions(options = {}) {
     ...whenDefined("normalizeFn", composedNormalizeFn),
     ...whenDefined("ariaRules", enforcement?.aria),
     ...whenDefined("childRules", enforcement?.children),
+    ...whenDefined("exclusiveChildren", enforcement?.exclusiveChildren),
+    ...whenDefined("allowText", enforcement?.allowText),
     ...whenDefined("allowedAs", enforcement?.allowedAs),
     ...whenDefined("precomputedClasses", styling?.precomputedClasses)
   });
@@ -2464,16 +2488,22 @@ function buildCoreRuntime(normalized) {
 }
 
 // ../../lib/adapter-utils/src/runtime/build-engines.ts
-function buildEngines(diagnostics, childRules, context) {
-  return childRules?.length ? { childrenEvaluator: new ChildrenEvaluator(childRules, diagnostics, context) } : {};
+function buildEngines(diagnostics, childRules, context, childrenOptions) {
+  const { exclusiveChildren, allowText } = childrenOptions ?? {};
+  return childRules?.length || exclusiveChildren || allowText === false ? {
+    childrenEvaluator: new ChildrenEvaluator(childRules ?? [], diagnostics, context, {
+      exclusiveChildren,
+      allowText
+    })
+  } : {};
 }
 
 // ../../lib/adapter-utils/src/runtime/resolve-adapter-common-options.ts
-import { throwDiagnostics as throwDiagnostics2, silentDiagnostics as silentDiagnostics2 } from "../_shared/diagnostics.js";
+import { throwDiagnostics as throwDiagnostics2, silentDiagnostics as silentDiagnostics2, resolveDiagnostics as resolveDiagnostics2 } from "../_shared/diagnostics.js";
 function resolveAdapterCommonOptions(options, defaultName = "PolymorphicComponent", defaultDiagnostics = throwDiagnostics2) {
   return {
     name: options.name ?? defaultName,
-    diagnostics: options.enforcement?.diagnostics ?? defaultDiagnostics
+    diagnostics: resolveDiagnostics2(options.enforcement?.diagnostics, defaultDiagnostics)
   };
 }
 
@@ -2518,7 +2548,11 @@ function buildRuntime(options) {
   const { childrenEvaluator } = buildEngines(
     normalized.diagnostics,
     normalized.enforcement?.children,
-    normalized.name
+    normalized.name,
+    {
+      exclusiveChildren: normalized.enforcement?.exclusiveChildren,
+      allowText: normalized.enforcement?.allowText
+    }
   );
   const filterProps = composeFilter(ownedKeys, normalized.filterProps);
   const slotValidator = new SlotValidator(normalized.name, normalized.diagnostics, "Snippet");

package/dist/vite-plugin/index.d.ts

@@ -165,6 +165,13 @@ type ComponentConstraint = {
     defaultTag?: string;
     /** True when `enforcement.aria` is a non-empty array literal in the factory call. */
     hasAriaRules: boolean;
+    /**
+     * True when `enforcement.exclusiveChildren` is statically `true` in the factory call.
+     * Only when this is true does an "over the max" child count constitute a real
+     * violation — enforcement.children is open-by-default, so extra unmatched children
+     * are otherwise allowed regardless of `totalMax`.
+     */
+    exclusiveChildren: boolean;
 };
 
 /** A diagnostic produced by the static analysis pass. */
@@ -208,6 +215,11 @@ type PluginOptions = {
  *   are skipped — their child count is unknowable at build time.
  * - Named const declarations: `export const X = factory(...)` and destructured
  *   patterns are not collected; cross-file analysis is future work.
+ *
+ * @example
+ * ```ts
+ * const diagnostics = analyze(source, 'Button.tsx', { severity: 'error' })
+ * ```
  */
 declare function analyze(code: string, filename: string, options?: PluginOptions): Diagnostic[];
 
@@ -228,6 +240,25 @@ declare function analyze(code: string, filename: string, options?: PluginOptions
  * - `styling.compounds` contains non-literal conditions or class values
  * - The total number of combinations exceeds MAX_COMBINATIONS
  * - The styling object already has a `precomputedClasses` property
+ *
+ * @example
+ * Before:
+ * ```ts
+ * styling: {
+ *   variants: { size: { sm: 'text-sm', lg: 'text-lg' } },
+ * }
+ * ```
+ * After:
+ * ```ts
+ * styling: {
+ *   variants: { size: { sm: 'text-sm', lg: 'text-lg' } },
+ *   precomputedClasses: {
+ *     '__none__:': '',
+ *     '__none__:size:s:sm': 'text-sm',
+ *     '__none__:size:s:lg': 'text-lg',
+ *   },
+ * }
+ * ```
  */
 
 /**

package/dist/vite-plugin/index.js

@@ -189,7 +189,7 @@ function asArray(node) {
   if (!node) return void 0;
   return ts.isArrayLiteralExpression(node) ? node : void 0;
 }
-function asPositiveInt(node) {
+function asNonNegativeInt(node) {
   if (!node) return void 0;
   if (ts.isNumericLiteral(node)) {
     const n = Number(node.text);
@@ -197,6 +197,17 @@ function asPositiveInt(node) {
   }
   return void 0;
 }
+function asBooleanLiteral(node) {
+  if (!node) return void 0;
+  switch (node.kind) {
+    case ts.SyntaxKind.TrueKeyword:
+      return true;
+    case ts.SyntaxKind.FalseKeyword:
+      return false;
+    default:
+      return void 0;
+  }
+}
 function isFactoryCall(call, names) {
   const { expression } = call;
   if (ts.isIdentifier(expression)) return names.has(expression.text);
@@ -204,7 +215,7 @@ function isFactoryCall(call, names) {
   return false;
 }
 function firstObjectArg(call) {
-  const [first] = call.arguments;
+  const first = call.arguments[0];
   return first && ts.isObjectLiteralExpression(first) ? first : void 0;
 }
 function* walk(node) {
@@ -316,11 +327,11 @@ function enumerateCombinations(variantMap) {
     return total <= MAX_COMBINATIONS;
   });
   if (!totalUnderMaxLimit) return null;
-  function rec(remaining) {
+  function enumerateRecursive(remaining) {
     if (remaining.length === 0) return [{}];
     const first = remaining[0];
     const rest = remaining.slice(1);
-    const restCombos = rec(rest);
+    const restCombos = enumerateRecursive(rest);
     const valueKeys = Object.keys(variantMap[first]);
     const out = [];
     iterate.forEach(restCombos, (combo) => {
@@ -331,7 +342,7 @@ function enumerateCombinations(variantMap) {
     });
     return out;
   }
-  return rec(keys2);
+  return enumerateRecursive(keys2);
 }
 function buildCacheKey(props) {
   const parts = Object.keys(props).sort().map((k) => `${k}:s:${props[k]}`);
@@ -459,8 +470,8 @@ function extractBound(element) {
   if (cardObj) {
     const minNode = getProperty(cardObj, "min");
     const maxNode = getProperty(cardObj, "max");
-    const min = asPositiveInt(minNode) ?? 0;
-    const max = asPositiveInt(maxNode);
+    const min = asNonNegativeInt(minNode) ?? 0;
+    const max = asNonNegativeInt(maxNode);
     if (min === 0 && max === void 0) {
       cardinality = { kind: "unbounded" };
     } else {
@@ -497,6 +508,8 @@ function processVariableStatement(node, calleeNames, out) {
     const ariaNode = enfObj ? getProperty(enfObj, "aria") : void 0;
     const ariaArr = asArray(ariaNode);
     const hasAriaRules = ariaArr !== void 0 && ariaArr.elements.length > 0;
+    const exclusiveChildrenNode = enfObj ? getProperty(enfObj, "exclusiveChildren") : void 0;
+    const exclusiveChildren = asBooleanLiteral(exclusiveChildrenNode) ?? false;
     const childrenProp = enfObj ? getProperty(enfObj, "children") : void 0;
     const childrenArr = asArray(childrenProp);
     const rules = [];
@@ -506,7 +519,7 @@ function processVariableStatement(node, calleeNames, out) {
         if (bound) rules.push(bound);
       });
     }
-    if (rules.length === 0 && !hasAriaRules && !defaultTag) return;
+    if (rules.length === 0 && !hasAriaRules && !defaultTag && !exclusiveChildren) return;
     let totalMin = 0;
     let totalMax = 0;
     iterate.forEach(rules, (rule) => {
@@ -522,7 +535,8 @@ function processVariableStatement(node, calleeNames, out) {
       totalMin,
       totalMax,
       ...defaultTag !== void 0 && { defaultTag },
-      hasAriaRules
+      hasAriaRules,
+      exclusiveChildren
     });
   });
 }
@@ -734,7 +748,7 @@ function analyzeJsxSites(source, constraints, severity) {
     const getPos = () => pos ??= source.getLineAndCharacterOfPosition(node.getStart(source));
     if (count !== void 0) {
       const c = byName.get(tagName);
-      if (c && (count.max < c.totalMin || count.min > c.totalMax)) {
+      if (c && (count.max < c.totalMin || c.exclusiveChildren && count.min > c.totalMax)) {
         const { line, character } = getPos();
         diagnostics.push({
           diagnostic: ViteDiagnostics.cardinalityViolation(
@@ -868,8 +882,8 @@ function diagnoseUsages(source, constraints, severity) {
     const constraint = byName.get(tagName);
     if (!constraint) return;
     if (count === void 0) return;
-    const { totalMin, totalMax, name } = constraint;
-    if (count.max < totalMin || count.min > totalMax) {
+    const { totalMin, totalMax, name, exclusiveChildren } = constraint;
+    if (count.max < totalMin || exclusiveChildren && count.min > totalMax) {
       const { line, character } = source.getLineAndCharacterOfPosition(node.getStart(source));
       diagnostics.push({
         diagnostic: ViteDiagnostics.cardinalityViolation(
@@ -948,9 +962,11 @@ var ConstraintRegistry = class {
         if (count === void 0) return;
         const constraint = this.resolveConstraint(fileId, tagName);
         if (!constraint) return;
-        const { totalMin, totalMax, name } = constraint;
+        const { totalMin, totalMax, name, exclusiveChildren } = constraint;
         const { min, max } = count;
-        if (max >= totalMin && min <= totalMax) return;
+        const tooFew = max < totalMin;
+        const tooMany = exclusiveChildren && min > totalMax;
+        if (!tooFew && !tooMany) return;
         result.push({
           fileId,
           diagnostic: ViteDiagnostics.cardinalityViolation(name, totalMin, totalMax, min, max),
@@ -1379,8 +1395,9 @@ function composeStatically(source, calleeNames, importedComponents = /* @__PURE_
 }
 
 // ../../plugins/vite/src/analyze.ts
+import { extname } from "path";
 function analyze(code, filename, options) {
-  const ext = filename.split(".").pop() ?? "";
+  const ext = extname(filename).slice(1);
   if (!JSX_EXTS.has(ext)) return [];
   const calleeNames = new Set(options?.calleeNames ?? DEFAULT_CALLEE_NAMES);
   const severity = options?.severity ?? "warning";

package/dist/vue/index.d.ts

@@ -1,5 +1,5 @@
 import { RequireAtLeastOne, Simplify, ReadonlyDeep } from 'type-fest';
-import { Diagnostics, DiagnosticInput } from '../_shared/diagnostics.js';
+import { Diagnostics, DiagnosticInput, DiagnosticsMode } from '../_shared/diagnostics.js';
 import * as vue from 'vue';
 import { AllowedComponentProps } from 'vue';
 
@@ -214,9 +214,25 @@ type AriaRule<C extends AriaContext = AriaContext> = (context: C) => readonly Ar
 type PropNormalizer = (props: Readonly<AnyRecord & IntrinsicProps>) => Partial<AnyRecord & IntrinsicProps>;
 
 type EnforcementOptions<TAllowed extends ElementType = ElementType> = {
-    readonly diagnostics?: Diagnostics;
+    /**
+     * Accepts a preset name (`'warn'`, `'throw'`, `'silent'`) or a full `Diagnostics`
+     * instance for custom reporting/policy. The string form needs no import from
+     * `@praxis-kit/diagnostics`.
+     */
+    readonly diagnostics?: Diagnostics | DiagnosticsMode;
     readonly aria?: readonly AriaRule[];
     readonly children?: readonly ChildRuleInput[];
+    /**
+     * When true, only children matching a `children` rule (or text, per `allowText`)
+     * are valid — anything else is rejected. Default: false (open — children not
+     * matching any rule are allowed).
+     */
+    readonly exclusiveChildren?: boolean;
+    /**
+     * When false, text/number child nodes are rejected regardless of exclusiveChildren
+     * or any listed rule. Default: true.
+     */
+    readonly allowText?: boolean;
     readonly props?: readonly PropNormalizer[];
     /** Restricts the `as` prop to this set of tags. Violations route through diagnostics. */
     readonly allowedAs?: readonly TAllowed[];