@usefragments/core 1.0.0

package/src/raw-html-canonical.ts

@@ -0,0 +1,179 @@
+export type RawHtmlPrecisionTier =
+  | "exact-html"
+  | "html-advisory"
+  | "input-type"
+  | "role-reimpl"
+  | "interactive-nonsemantic"
+  | "icon-only";
+
+export interface RawHtmlCanonicalMatch {
+  canonical: string;
+  tier: RawHtmlPrecisionTier;
+}
+
+const EXACT_HTML_CANONICALS = new Map<string, string>([["button", "Button"]]);
+
+const ADVISORY_HTML_CANONICALS = new Map<string, string>([
+  ["textarea", "Textarea"],
+  ["select", "Select"],
+  ["dialog", "Dialog"],
+  ["progress", "Progress"],
+  ["details", "Collapsible"],
+  ["table", "Table"],
+]);
+
+const INPUT_TYPE_CANONICALS = new Map<string, string>([
+  ["checkbox", "Checkbox"],
+  ["radio", "Radio"],
+  ["number", "NumberInput"],
+  ["password", "PasswordInput"],
+  ["range", "Slider"],
+]);
+
+const ROLE_CANONICALS = new Map<string, string>([
+  ["button", "Button"],
+  ["checkbox", "Checkbox"],
+  ["radio", "Radio"],
+  ["switch", "Switch"],
+  ["tab", "Tabs"],
+  ["tablist", "Tabs"],
+  ["dialog", "Dialog"],
+  ["menu", "Menu"],
+  ["status", "Alert"],
+]);
+
+export const RAW_HTML_CANONICAL_TAGS = Object.freeze(
+  Array.from(EXACT_HTML_CANONICALS, ([tagName, canonical]) => ({
+    tagName,
+    canonical,
+    tier: "exact-html" as const,
+  }))
+);
+
+export const RAW_HTML_ADVISORY_TAGS = Object.freeze(
+  Array.from(ADVISORY_HTML_CANONICALS, ([tagName, canonical]) => ({
+    tagName,
+    canonical,
+    tier: "html-advisory" as const,
+  }))
+);
+
+export const RAW_HTML_INPUT_TYPE_CANONICALS = Object.freeze(
+  Array.from(INPUT_TYPE_CANONICALS, ([type, canonical]) => ({
+    type,
+    canonical,
+    tier: "input-type" as const,
+  }))
+);
+
+export const RAW_HTML_ROLE_CANONICALS = Object.freeze(
+  Array.from(ROLE_CANONICALS, ([role, canonical]) => ({
+    role,
+    canonical,
+    tier: "role-reimpl" as const,
+  }))
+);
+
+export function resolveCanonicalForRawHtml(
+  tagName: string,
+  inputType?: string
+): RawHtmlCanonicalMatch | null {
+  const tag = tagName.toLowerCase();
+  if (tag === "input") {
+    const normalizedType = inputType?.trim().toLowerCase();
+    if (!normalizedType) return null;
+    const canonical = INPUT_TYPE_CANONICALS.get(normalizedType);
+    return canonical ? { canonical, tier: "input-type" } : null;
+  }
+
+  const exactCanonical = EXACT_HTML_CANONICALS.get(tag);
+  if (exactCanonical) return { canonical: exactCanonical, tier: "exact-html" };
+  const advisoryCanonical = ADVISORY_HTML_CANONICALS.get(tag);
+  return advisoryCanonical ? { canonical: advisoryCanonical, tier: "html-advisory" } : null;
+}
+
+export function resolveCanonicalForAriaRole(role: string): RawHtmlCanonicalMatch | null {
+  const canonical = ROLE_CANONICALS.get(role.trim().toLowerCase());
+  return canonical ? { canonical, tier: "role-reimpl" } : null;
+}
+
+export function isRawHtmlAdvisoryTier(tier: RawHtmlPrecisionTier): boolean {
+  return (
+    tier === "html-advisory" ||
+    tier === "role-reimpl" ||
+    tier === "interactive-nonsemantic" ||
+    tier === "icon-only"
+  );
+}
+
+/**
+ * Low-frequency, typically-1:1 semantic tags where a per-component inferred
+ * `htmlEquivalent` mapping is safe even with a custom-named component
+ * (`<dialog>` → Modal). Mirrors `ADVISORY_HTML_CANONICALS` + the `input` family.
+ *
+ * Deliberately EXCLUDES generic structural containers (`div`, `span`) and the
+ * ambiguous common tags (`button`, `a`): those are handled by the stricter
+ * agreement check in `isEnforceableHtmlEquivalent`.
+ */
+const SEMANTIC_HTML_EQUIVALENT_TAGS = new Set<string>([
+  "input",
+  "textarea",
+  "select",
+  "dialog",
+  "progress",
+  "details",
+  "table",
+]);
+
+/**
+ * Specific interactive tags that an EXPLICITLY-DECLARED project mapping may
+ * enforce against ANY canonical component NAME — making the rule component-
+ * library agnostic (so `@acme/ui`'s `AcmeButton` fires on a raw `<button>`, not
+ * only the curated built-in "Button").
+ *
+ * Deliberately EXCLUDES generic structural containers (`div`, `span`): even an
+ * explicit declaration must never turn every `<div>` into a bespoke
+ * re-implementation. The `explicit` gate only applies to user-declared tag
+ * mappings (provenance: `localCanonical.resolves`), never to inferred
+ * `htmlEquivalent`s — so the `<button>` → Chip flood class stays name-gated.
+ */
+const EXPLICITLY_ENFORCEABLE_AMBIGUOUS_TAGS = new Set<string>(["button", "a"]);
+
+/**
+ * Decide whether a per-component `htmlEquivalent` mapping (raw `tag` → a
+ * `canonical` component) may drive a bare-tag canonical-usage finding.
+ *
+ * The contract:
+ * - Low-frequency SEMANTIC tags (dialog, select, textarea, input, …) are always
+ *   enforceable, so a custom-named component (`<dialog>` → Modal) still maps.
+ * - Common/ambiguous tags (button, a, …) enforce ONLY when the mapping AGREES
+ *   with the framework's curated canonical for that tag — so `<button>` → Button
+ *   fires, but `<button>` → Chip does not.
+ * - Generic structural containers (div, span) have no curated answer and are not
+ *   semantic → never enforce.
+ *
+ * This is the guard that stops the canonical-usage flood: a library component
+ * being built on a `<div>` must not make every `<div>` a bespoke re-implementation
+ * of it (every `<div>` → Accordion, every `<span>` → Badge, every `<button>` → Chip).
+ */
+export function isEnforceableHtmlEquivalent(args: {
+  tag: string;
+  canonical: string;
+  inputType?: string;
+  /**
+   * The mapping is an EXPLICIT project declaration of this tag → component
+   * (provenance: `localCanonical.resolves`), not a low-confidence inferred
+   * `htmlEquivalent`. Explicit declarations enforce a specific interactive tag
+   * (`button`/`a`) against any canonical NAME — the agnosticism path — while
+   * inferred mappings stay name-gated to the curated canonical (the flood
+   * guard). Generic containers (`div`/`span`) are never enforceable even when
+   * explicit.
+   */
+  explicit?: boolean;
+}): boolean {
+  const tag = args.tag.toLowerCase();
+  if (SEMANTIC_HTML_EQUIVALENT_TAGS.has(tag)) return true;
+  if (args.explicit && EXPLICITLY_ENFORCEABLE_AMBIGUOUS_TAGS.has(tag)) return true;
+  const builtIn = resolveCanonicalForRawHtml(tag, args.inputType);
+  return builtIn !== null && builtIn.canonical === args.canonical;
+}

package/src/react-types.ts

@@ -0,0 +1,21 @@
+/**
+ * React-specific types for Fragments.
+ *
+ * Import from '@usefragments/core/react' when you need React-typed
+ * component definitions. The main '@usefragments/core' entrypoint
+ * works without React installed.
+ */
+
+import type { ComponentType, ReactNode, JSX } from 'react';
+
+/**
+ * A React component that can be used in a fragment definition.
+ * This type is intentionally broad to support various React component patterns
+ * including FC, forwardRef, memo, and class components across different React versions.
+ */
+export type FragmentComponent<TProps = any> =
+  | ComponentType<TProps>
+  | ((props: TProps) => ReactNode | JSX.Element | null);
+
+// Re-export definition types for convenience
+export type { FragmentDefinition, FragmentDefinitionV2 } from './types.js';

package/src/registry-install-plan.ts

@@ -0,0 +1,344 @@
+import { portableRepoPathError } from "./config-paths.js";
+import {
+  REGISTRY_INSTALL_RECEIPT_SCHEMA_VERSION,
+  hashRegistryFileContent,
+  registryInstallReceiptSchema,
+  type RegistryArtifact,
+  type RegistryDependency,
+  type RegistryFile,
+  type RegistryInstallReceipt,
+} from "./registry.js";
+
+export interface RegistryWritePlan {
+  path: string;
+  sourcePath: string;
+  content: string;
+  componentId?: string;
+}
+
+export interface BuildRegistryInstallPlanInput {
+  artifact: RegistryArtifact;
+  requestedComponents: readonly string[];
+  targetPath: string;
+  all?: boolean;
+  includeTests?: boolean;
+}
+
+export interface RegistryInstallPlan {
+  componentNames: string[];
+  plans: RegistryWritePlan[];
+  dependencies: RegistryDependency[];
+}
+
+export function normalizeRegistryRepoPath(path: string): string {
+  return path
+    .split("\\")
+    .join("/")
+    .replace(/^\.\/+/, "");
+}
+
+export function assertPortableRegistryPath(path: string, label: string): string {
+  const normalized = normalizeRegistryRepoPath(path);
+  const error = portableRepoPathError(normalized);
+  if (error) throw new Error(`${label}: ${error}`);
+  return normalized;
+}
+
+function joinRegistryPath(...parts: string[]): string {
+  return normalizeRegistryRepoPath(parts.filter(Boolean).join("/"));
+}
+
+export function sourceToRegistryTargetPath(targetRoot: string, sourcePath: string): string {
+  const source = normalizeRegistryRepoPath(sourcePath);
+  const withoutSrc = source.startsWith("src/") ? source.slice("src/".length) : source;
+  return assertPortableRegistryPath(
+    joinRegistryPath(targetRoot, withoutSrc),
+    "Registry install target"
+  );
+}
+
+export function selectedRegistryComponentNames(
+  artifact: RegistryArtifact,
+  requested: readonly string[],
+  all: boolean | undefined
+): string[] {
+  if (all || requested.includes("*")) {
+    return Object.keys(artifact.manifest.components).sort((left, right) =>
+      left.localeCompare(right)
+    );
+  }
+  if (requested.length === 0) {
+    throw new Error("Choose at least one registry component to install.");
+  }
+  for (const name of requested) {
+    if (!artifact.manifest.components[name]) {
+      throw new Error(`Unknown registry component ${name}`);
+    }
+  }
+  return [...new Set(requested)].sort();
+}
+
+function installsCompleteRegistry(
+  artifact: RegistryArtifact,
+  componentNames: readonly string[]
+): boolean {
+  const allComponents = Object.keys(artifact.manifest.components);
+  return (
+    componentNames.length === allComponents.length &&
+    allComponents.every((name) => componentNames.includes(name))
+  );
+}
+
+function shouldInstallFile(file: RegistryFile, includeTests: boolean | undefined): boolean {
+  if (includeTests) return true;
+  return file.role !== "test" && file.role !== "story";
+}
+
+function dependencyKey(dependency: RegistryDependency): string {
+  return `${dependency.type}:${dependency.name}:${dependency.versionRange}:${dependency.optional ? 1 : 0}`;
+}
+
+export function collectRegistryInstallDependencies(
+  artifact: RegistryArtifact,
+  componentNames: readonly string[]
+): RegistryDependency[] {
+  const dependencies = new Map<string, RegistryDependency>();
+  for (const dependency of artifact.manifest.dependencies) {
+    dependencies.set(dependencyKey(dependency), dependency);
+  }
+  for (const name of componentNames) {
+    const component = artifact.manifest.components[name];
+    for (const dependency of [...component.runtimeDependencies, ...component.peerDependencies]) {
+      dependencies.set(dependencyKey(dependency), dependency);
+    }
+  }
+  return [...dependencies.values()].sort((left, right) => left.name.localeCompare(right.name));
+}
+
+function collectComponentWritePlan(args: {
+  artifact: RegistryArtifact;
+  componentNames: readonly string[];
+  targetPath: string;
+  includeTests?: boolean;
+}): RegistryWritePlan[] {
+  const writes = new Map<string, RegistryWritePlan>();
+  for (const componentName of args.componentNames) {
+    const component = args.artifact.manifest.components[componentName];
+    for (const file of component.files) {
+      if (!shouldInstallFile(file, args.includeTests)) continue;
+      const content = args.artifact.files[file.path];
+      if (!content) throw new Error(`Artifact is missing file content for ${file.path}`);
+      const target = sourceToRegistryTargetPath(args.targetPath, file.path);
+      writes.set(target, {
+        path: target,
+        sourcePath: file.path,
+        content: content.content,
+        componentId: component.componentId,
+      });
+    }
+  }
+  return [...writes.values()].sort((left, right) => left.path.localeCompare(right.path));
+}
+
+function rewriteInstalledPackagePath(value: string): string {
+  if (value.startsWith("./src/")) return `./${value.slice("./src/".length)}`;
+  if (value.startsWith("src/")) return value.slice("src/".length);
+  return value;
+}
+
+function rewriteInstalledPackageExport(value: unknown): unknown {
+  if (typeof value === "string") return rewriteInstalledPackagePath(value);
+  if (!value || typeof value !== "object" || Array.isArray(value)) return value;
+  return Object.fromEntries(
+    Object.entries(value).map(([key, nested]) => [key, rewriteInstalledPackageExport(nested)])
+  );
+}
+
+function rewriteInstalledPackageJson(content: string): string {
+  const parsed = JSON.parse(content) as {
+    name?: string;
+    version?: string;
+    type?: string;
+    sideEffects?: unknown;
+    main?: string;
+    types?: string;
+    fragments?: string;
+    exports?: unknown;
+    dependencies?: unknown;
+    peerDependencies?: unknown;
+    peerDependenciesMeta?: unknown;
+  };
+
+  const installed = {
+    ...(parsed.name && { name: parsed.name }),
+    ...(parsed.version && { version: parsed.version }),
+    private: true,
+    ...(parsed.type && { type: parsed.type }),
+    ...(parsed.sideEffects !== undefined && { sideEffects: parsed.sideEffects }),
+    ...(parsed.main && { main: rewriteInstalledPackagePath(parsed.main) }),
+    ...(parsed.types && { types: rewriteInstalledPackagePath(parsed.types) }),
+    fragments: rewriteInstalledPackagePath(parsed.fragments ?? "fragments.json"),
+    ...(parsed.exports !== undefined && {
+      exports: rewriteInstalledPackageExport(parsed.exports),
+    }),
+    ...(parsed.dependencies !== undefined && { dependencies: parsed.dependencies }),
+    ...(parsed.peerDependencies !== undefined && { peerDependencies: parsed.peerDependencies }),
+    ...(parsed.peerDependenciesMeta !== undefined && {
+      peerDependenciesMeta: parsed.peerDependenciesMeta,
+    }),
+  };
+
+  return `${JSON.stringify(installed, null, 2)}\n`;
+}
+
+function collectPackageWritePlan(args: {
+  artifact: RegistryArtifact;
+  targetPath: string;
+  includeTests?: boolean;
+}): RegistryWritePlan[] {
+  const writes = new Map<string, RegistryWritePlan>();
+  const packageFiles = new Map(
+    args.artifact.manifest.packageFiles.map((file) => [file.path, file])
+  );
+  for (const entrypoint of args.artifact.manifest.entrypoints) {
+    const file = packageFiles.get(entrypoint.sourcePath);
+    if (file) continue;
+    const content = args.artifact.files[entrypoint.sourcePath];
+    if (!content) throw new Error(`Artifact is missing file content for ${entrypoint.sourcePath}`);
+    packageFiles.set(entrypoint.sourcePath, {
+      path: entrypoint.sourcePath,
+      role: "barrel",
+      sha256: content.sha256,
+      size: content.size,
+      contentType: content.contentType,
+      contentRef: `sha256:${content.sha256}`,
+    });
+  }
+
+  for (const file of packageFiles.values()) {
+    if (!shouldInstallFile(file, args.includeTests)) continue;
+    const content = args.artifact.files[file.path];
+    if (!content) throw new Error(`Artifact is missing file content for ${file.path}`);
+    const target = sourceToRegistryTargetPath(args.targetPath, file.path);
+    writes.set(target, {
+      path: target,
+      sourcePath: file.path,
+      content:
+        file.path === "package.json"
+          ? rewriteInstalledPackageJson(content.content)
+          : content.content,
+    });
+  }
+
+  return [...writes.values()].sort((left, right) => left.path.localeCompare(right.path));
+}
+
+function generatedIndexPlan(args: {
+  componentNames: readonly string[];
+  targetPath: string;
+  artifact: RegistryArtifact;
+}): RegistryWritePlan {
+  const lines = args.componentNames.map((name) => {
+    const component = args.artifact.manifest.components[name];
+    const exportName = component.exports[0]?.name ?? component.name;
+    return `export { ${exportName} } from "./components/${component.componentId}";`;
+  });
+  return {
+    path: assertPortableRegistryPath(
+      joinRegistryPath(args.targetPath, "index.ts"),
+      "Registry index target"
+    ),
+    sourcePath: "registry/generated-index.ts",
+    content: `${lines.join("\n")}\n`,
+  };
+}
+
+function dedupePlans(plans: readonly RegistryWritePlan[]): RegistryWritePlan[] {
+  const byPath = new Map<string, RegistryWritePlan>();
+  for (const plan of plans) {
+    const existing = byPath.get(plan.path);
+    if (existing && existing.content !== plan.content) {
+      throw new Error(`Conflicting registry write plans for ${plan.path}`);
+    }
+    byPath.set(plan.path, existing ?? plan);
+  }
+  return [...byPath.values()].sort((left, right) => left.path.localeCompare(right.path));
+}
+
+export function buildRegistryInstallPlan(
+  input: BuildRegistryInstallPlanInput
+): RegistryInstallPlan {
+  const targetPath = assertPortableRegistryPath(input.targetPath, "Registry target");
+  const componentNames = selectedRegistryComponentNames(
+    input.artifact,
+    input.requestedComponents,
+    input.all
+  );
+  const dependencies = collectRegistryInstallDependencies(input.artifact, componentNames);
+  const isCompleteInstall = installsCompleteRegistry(input.artifact, componentNames);
+  const hasPackageRoot = input.artifact.manifest.entrypoints.some(
+    (entrypoint) => entrypoint.specifier === "."
+  );
+  const plans = dedupePlans([
+    ...(isCompleteInstall
+      ? collectPackageWritePlan({
+          artifact: input.artifact,
+          targetPath,
+          includeTests: input.includeTests,
+        })
+      : []),
+    ...collectComponentWritePlan({
+      artifact: input.artifact,
+      componentNames,
+      targetPath,
+      includeTests: input.includeTests,
+    }),
+    ...(isCompleteInstall && hasPackageRoot
+      ? []
+      : [generatedIndexPlan({ artifact: input.artifact, componentNames, targetPath })]),
+  ]);
+
+  return { componentNames, plans, dependencies };
+}
+
+export function buildRegistryInstallReceipt(args: {
+  artifact: RegistryArtifact;
+  targetPath: string;
+  importPath: string;
+  componentNames: readonly string[];
+  plans: readonly RegistryWritePlan[];
+  dependencies: readonly RegistryDependency[];
+  installedAt?: string;
+}): RegistryInstallReceipt {
+  const installedComponents = args.componentNames.map((name) => {
+    const component = args.artifact.manifest.components[name];
+    return {
+      componentId: component.componentId,
+      publicRef: component.publicRef,
+      name: component.name,
+      files: args.plans
+        .filter((plan) => plan.componentId === component.componentId)
+        .map((plan) => plan.path),
+    };
+  });
+
+  return registryInstallReceiptSchema.parse({
+    schemaVersion: REGISTRY_INSTALL_RECEIPT_SCHEMA_VERSION,
+    registryId: args.artifact.manifest.registryId,
+    registryVersion: args.artifact.manifest.version,
+    registryHash: args.artifact.manifest.registryHash,
+    fcid: args.artifact.manifest.fcid,
+    channel: args.artifact.manifest.channel,
+    targetPath: assertPortableRegistryPath(args.targetPath, "Registry target"),
+    importPath: args.importPath,
+    installedComponents,
+    files: args.plans.map((plan) => ({
+      path: plan.path,
+      sourcePath: plan.sourcePath,
+      sha256: hashRegistryFileContent(plan.content),
+      componentId: plan.componentId,
+    })),
+    dependencies: args.dependencies,
+    installedAt: args.installedAt ?? new Date().toISOString(),
+  });
+}