@usefragments/core 1.9.1 → 1.10.1

package/src/governance.ts

@@ -355,6 +355,7 @@ export const governanceConfigSchema = z
       .object({
         failOnWarnings: z.boolean().optional(),
         failOnInert: z.boolean().optional(),
+        failOnAdoptionRegression: z.boolean().optional(),
       })
       .passthrough()
       .optional(),
@@ -443,9 +444,13 @@ export interface GovernanceConfig {
   overrides?: ComponentPolicyOverride[];
 
   /**
-   * Governance CI rendering options: `failOnWarnings` makes warning findings fail the
-   * `--ci` verdict, `failOnInert` makes inert-config diagnostics (FUI9004-FUI9008) fail
-   * it. Both are opt-in; `--allow-inert` bypasses the inert gates.
+   * Governance CI rendering options. Under `--ci`, `failOnWarnings` defaults to `true`
+   * when absent; set it to `false` to keep warning findings reported but advisory.
+   * `failOnInert` is opt-in and makes inert-config diagnostics (FUI9004-FUI9008) fail
+   * the verdict; `--allow-inert` bypasses the inert gates.
+   * `failOnAdoptionRegression` is opt-in and makes `check --ci` compare the
+   * current component-identity adoption percentage with the committed
+   * `.fragments/adoption-baseline.json` floor.
    */
   ci?: {
     failOnWarnings?: boolean;
@@ -456,6 +461,13 @@ export interface GovernanceConfig {
      * bypasses it, like the governance-inert gate.
      */
     failOnInert?: boolean;
+    /**
+     * Fail `check --ci` when measurable component-identity adoption falls below
+     * the committed local floor. Update the floor through `check
+     * --update-baseline`; accepting a lower floor additionally requires
+     * `--allow-regression`.
+     */
+    failOnAdoptionRegression?: boolean;
     [key: string]: unknown;
   };
   [key: string]: unknown;

package/src/index.ts

@@ -501,28 +501,6 @@ export {
 } from "./policy-exclude.js";
 export type { PolicyExclude, PolicyExcludeInput } from "./policy-exclude.js";
 
-// Story adapter (runtime conversion of Storybook modules)
-export {
-  storyModuleToFragment,
-  setPreviewConfig,
-  getPreviewConfig,
-  // Re-export @storybook/csf utilities
-  toId,
-  storyNameFromExport,
-  isExportStory,
-} from "./storyAdapter.js";
-export type {
-  StoryModule,
-  StoryMeta,
-  Story,
-  StoryArgType,
-  StoryContext,
-  Decorator,
-  Loader,
-  PreviewConfig,
-  CSF2Story,
-} from "./storyAdapter.js";
-
 // Storybook adapter filtering
 export {
   checkStoryExclusion,
@@ -640,19 +618,6 @@ export type {
   CompositionGuideline,
 } from "./composition.js";
 
-// Shared preview runtime
-export {
-  executeVariantLoaders,
-  resolvePreviewRuntimeState,
-  usePreviewVariantRuntime,
-  PreviewVariantRuntime,
-} from "./preview-runtime.js";
-export type {
-  PreviewVariantLike,
-  PreviewRuntimeState,
-  PreviewRuntimeOptions,
-} from "./preview-runtime.js";
-
 // Component discovery
 export { discoverComponents, isReactComponent } from "./component-discovery.js";
 export type { DiscoverComponentsOptions } from "./component-discovery.js";

package/src/react-create-element.test.ts

@@ -0,0 +1,22 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+describe("getCreateElement", () => {
+  afterEach(() => {
+    vi.resetModules();
+    vi.doUnmock("node:module");
+  });
+
+  it("throws a clear error when react cannot be resolved", async () => {
+    vi.doMock("node:module", () => ({
+      createRequire: () => () => {
+        throw new Error("Cannot find module 'react'");
+      },
+    }));
+
+    const { getCreateElement } = await import("./react-create-element.js");
+
+    expect(() => getCreateElement()).toThrow(
+      '@usefragments/core: story rendering requires the optional peer dependency "react" (>=18). Install react to use storyModuleToFragment default render paths.',
+    );
+  });
+});

package/src/react-create-element.ts

@@ -0,0 +1,12 @@
+import { createRequire } from "node:module";
+
+export function getCreateElement(): typeof import("react")["createElement"] {
+  try {
+    return (createRequire(import.meta.url)("react") as typeof import("react")).createElement;
+  } catch (error) {
+    throw new Error(
+      '@usefragments/core: story rendering requires the optional peer dependency "react" (>=18). Install react to use storyModuleToFragment default render paths.',
+      { cause: error instanceof Error ? error : undefined },
+    );
+  }
+}

package/src/react-types.ts

@@ -3,7 +3,8 @@
  *
  * Import from '@usefragments/core/react' when you need React-typed
  * component definitions. The main '@usefragments/core' entrypoint
- * works without React installed.
+ * works without React installed — story and preview-runtime APIs live on
+ * `@usefragments/core/story` and `@usefragments/core/preview-runtime`.
  */
 
 import type { ComponentType, ReactNode, JSX } from 'react';

package/src/rules/a11y-required-accessible-name.ts

@@ -24,6 +24,7 @@ import type {
   UsageNodeFact,
   UsagePropResolvedFact,
 } from "../facts/index.js";
+import { z } from "zod";
 
 import { isAriaHidden } from "./a11y-utils.js";
 import { makeFinding } from "./finding.js";
@@ -31,7 +32,16 @@ import type { Finding } from "./types.js";
 import { indexPropsByNodeId, indexTextChildrenByNodeId } from "./utils.js";
 
 export const RULE_ID = "a11y/required-accessible-name";
-export const RULE_VERSION = "2";
+export const RULE_VERSION = "3";
+
+export const a11yRequiredAccessibleNameOptionsSchema = z.object({
+  ignoreParents: z.array(z.string().min(1)).optional(),
+  ignoreSpread: z.boolean().optional(),
+});
+
+export type A11yRequiredAccessibleNameOptions = z.infer<
+  typeof a11yRequiredAccessibleNameOptionsSchema
+>;
 
 const NAME_SOURCE_PROPS = new Set(["aria-label", "aria-labelledby", "title"]);
 const COMPONENT_NAME_SOURCE_PROPS = new Set([...NAME_SOURCE_PROPS, "label"]);
@@ -57,7 +67,12 @@ export function ruleA11yRequiredAccessibleName(ix: FactIndex): Finding[] {
     ix.byKind("usage_child_content").map((content) => [content.nodeId, content])
   );
   const globalPolicy = ix.policy.ruleConfig(RULE_ID);
+  const parsedOptions = a11yRequiredAccessibleNameOptionsSchema.safeParse(globalPolicy?.options);
+  const options: A11yRequiredAccessibleNameOptions = parsedOptions.success
+    ? parsedOptions.data
+    : {};
   const usageByNode = new Map(ix.byKind("usage_component").map((usage) => [usage.nodeId, usage]));
+  const usageNodes = ix.byKind("usage_node");
   const definitions = new Map(
     ix.byKind("component_definition").map((definition) => [definition.componentKey, definition])
   );
@@ -73,6 +88,7 @@ export function ruleA11yRequiredAccessibleName(ix: FactIndex): Finding[] {
       globalPolicy?.enabled === true &&
       requiresAccessibleName(node, usageComponent, definitions, props);
     if (!componentPolicy && !genericControl) continue;
+    if (isInsideIgnoredAttributeParent(node, usageNodes, options.ignoreParents)) continue;
 
     if (
       hasAccessibleName(
@@ -86,11 +102,16 @@ export function ruleA11yRequiredAccessibleName(ix: FactIndex): Finding[] {
       continue;
     }
 
+    const hasSpreadProps = props.some((prop) => prop.resolution === "spread");
+    if (hasSpreadProps && options.ignoreSpread === true) continue;
+
     findings.push(
       makeFinding({
         ruleId: RULE_ID,
         ruleVersion: RULE_VERSION,
-        severity: componentPolicy?.severity ?? globalPolicy?.severity ?? "warn",
+        severity: hasSpreadProps
+          ? "minor"
+          : (componentPolicy?.severity ?? globalPolicy?.severity ?? "warn"),
         message: `<${node.element}> has no accessible name. ${
           componentPolicy?.because ??
           "Add visible text, aria-label, aria-labelledby, or a component label."
@@ -119,6 +140,28 @@ export function ruleA11yRequiredAccessibleName(ix: FactIndex): Finding[] {
   return findings;
 }
 
+function isInsideIgnoredAttributeParent(
+  node: UsageNodeFact,
+  usageNodes: readonly UsageNodeFact[],
+  ignoreParents: readonly string[] | undefined
+): boolean {
+  if (!ignoreParents?.length || !node.nodePath.includes("/attr:")) return false;
+  const ignored = new Set(ignoreParents);
+  const segments = node.nodePath.split("/");
+  const ancestorPaths = new Set<string>();
+  for (let index = 1; index < segments.length; index += 1) {
+    if (segments[index].startsWith("attr:")) {
+      ancestorPaths.add(segments.slice(0, index).join("/"));
+    }
+  }
+  return usageNodes.some(
+    (candidate) =>
+      candidate.file === node.file &&
+      ancestorPaths.has(candidate.nodePath) &&
+      ignored.has(candidate.element)
+  );
+}
+
 function hasAccessibleName(
   props: UsagePropResolvedFact[],
   textChildren: ReadonlyArray<{ text: string }>,

package/src/rules/index.ts

@@ -8,8 +8,10 @@
  */
 
 import type { FactIndex } from "../facts/index.js";
+import type { ZodTypeAny } from "zod";
 
 import {
+  a11yRequiredAccessibleNameOptionsSchema,
   RULE_VERSION as A11Y_REQUIRED_ACCESSIBLE_NAME_VERSION,
   ruleA11yRequiredAccessibleName,
 } from "./a11y-required-accessible-name.js";
@@ -44,6 +46,7 @@ export interface Rule {
   id: string;
   version: string;
   run: RuleFn;
+  optionsSchema?: ZodTypeAny;
 }
 
 export const RULES: readonly Rule[] = [
@@ -156,6 +159,7 @@ export const RULES: readonly Rule[] = [
     id: "a11y/required-accessible-name",
     version: A11Y_REQUIRED_ACCESSIBLE_NAME_VERSION,
     run: ruleA11yRequiredAccessibleName,
+    optionsSchema: a11yRequiredAccessibleNameOptionsSchema,
   },
   {
     id: "a11y/standard",

package/src/rules/rules.test.ts

@@ -36,6 +36,7 @@ import {
   runRules,
 } from "../index.js";
 import type { CanonicalBridgeV1, Fact, FactId } from "../index.js";
+import { makeGovernanceRuleConfigFact } from "../facts/index.js";
 import { RULE_VERSION as A11Y_REQUIRED_ACCESSIBLE_NAME_VERSION } from "./a11y-required-accessible-name.js";
 import { makeFinding } from "./finding.js";
 
@@ -1425,6 +1426,77 @@ describe("a11y/required-accessible-name", () => {
     expect(ruleA11yRequiredAccessibleName(ix)).toHaveLength(0);
   });
 
+  it("ignores controls rendered through an ignored same-file attribute parent", () => {
+    const ix = emptyIndexWithGovernance();
+    ix.add(
+      makeGovernanceRuleConfigFact({
+        ruleId: "a11y/required-accessible-name",
+        enabled: true,
+        options: { ignoreParents: ["FormControlLabel"] },
+      })
+    );
+    ix.add(
+      makeUsageNodeFact({
+        file: "apps/x.tsx",
+        nodePath: "0:0",
+        element: "FormControlLabel",
+        location: { file: "apps/x.tsx", line: 1, column: 0 },
+      })
+    );
+    addButtonUsage(ix, {
+      file: "apps/x.tsx",
+      nodePath: "0:0/attr:control/0:0",
+      line: 1,
+      column: 28,
+    });
+
+    expect(ruleA11yRequiredAccessibleName(ix)).toHaveLength(0);
+  });
+
+  it("demotes an unnamed component with spread props to minor", () => {
+    const ix = emptyIndexWithGovernance();
+    addButtonUsage(ix, {
+      file: "apps/x.tsx",
+      nodePath: "0:0",
+      line: 1,
+      column: 0,
+      props: [{ prop: "...props", resolution: "spread" }],
+    });
+
+    expect(ruleA11yRequiredAccessibleName(ix)).toMatchObject([{ severity: "minor" }]);
+  });
+
+  it("skips an unnamed component with spread props when ignoreSpread is enabled", () => {
+    const ix = emptyIndexWithGovernance();
+    ix.add(
+      makeGovernanceRuleConfigFact({
+        ruleId: "a11y/required-accessible-name",
+        enabled: true,
+        options: { ignoreSpread: true },
+      })
+    );
+    addButtonUsage(ix, {
+      file: "apps/x.tsx",
+      nodePath: "0:0",
+      line: 1,
+      column: 0,
+      props: [{ prop: "...props", resolution: "spread" }],
+    });
+
+    expect(ruleA11yRequiredAccessibleName(ix)).toHaveLength(0);
+  });
+
+  it("registers ignoreParents and ignoreSpread as supported rule options", () => {
+    const registered = RULES.find((rule) => rule.id === "a11y/required-accessible-name");
+
+    expect(
+      registered?.optionsSchema?.safeParse({
+        ignoreParents: ["FormControlLabel"],
+        ignoreSpread: true,
+      }).success
+    ).toBe(true);
+  });
+
   it("keeps the registry version in lockstep with the emitted finding version", () => {
     const registered = RULES.find((rule) => rule.id === "a11y/required-accessible-name");
     expect(registered?.version).toBe(A11Y_REQUIRED_ACCESSIBLE_NAME_VERSION);

package/src/storyAdapter.ts

@@ -8,8 +8,9 @@
  * Supports Storybook 8.x with both CSF2 (Template.bind) and CSF3 (object stories).
  */
 
-import { createElement, type ComponentType, type ReactNode } from "react";
+import type { ComponentType, ReactNode } from "react";
 import { toId, storyNameFromExport, isExportStory } from "./storybook-csf.js";
+import { getCreateElement } from "./react-create-element.js";
 import type {
   FragmentDefinition,
   FragmentMeta,
@@ -711,7 +712,7 @@ function createRenderFunction(
           : meta.render!(args);
     } else {
       // Default: render component with args
-      renderFn = () => createElement(component, args);
+      renderFn = () => getCreateElement()(component, args);
     }
 
     // Collect decorators in Storybook order