dslinter 0.1.5 → 0.2.0

package/src/playground/buildPlaygroundEntriesFromReport.ts

@@ -1,13 +1,108 @@
-import { createElement, type ComponentType } from "react";
+import { createElement } from "react";
 import type { PlaygroundArgs, PlaygroundControl } from "../types/controls";
-import type { DeclaredPropKind, PlaygroundSpec, WorkspaceReport } from "../types/report";
-import type { PlaygroundEntry, PlaygroundMeta, PlaygroundPreviewComponent } from "../types/playground";
+import type { PlaygroundSpec, UsageSummary, WorkspaceReport } from "../types/report";
+import type { PlaygroundEntry, PlaygroundMeta } from "../types/playground";
+import type { PlaygroundPreviewComponent } from "../types/preview";
 import {
   defaultEmbedGlobKeyFromRelPath,
   diagnosePlaygroundJoinSkips,
   logPlaygroundJoinSkips,
+  resolveModuleKeyForRelPath,
   type PlaygroundJoinSkip,
 } from "./playgroundJoin";
+import {
+  definitionPathsForName,
+  isCatalogComponentHidden,
+} from "../dashboard/catalogVisibility";
+import { collectDefinedPlaygrounds } from "./collectDefinedPlaygrounds";
+import { catalogIdFromPlaygroundExport } from "./catalogIdFromPlaygroundExport";
+import {
+  buildCompoundPlaygroundEntries,
+  upgradeRootEntriesWithCompoundPreview,
+} from "./buildCompoundPlaygroundEntries";
+import { mergePlaygroundEntries } from "./mergePlaygroundEntries";
+import { getModuleExport } from "./playgroundModuleExport";
+import { mergeReportControlsForKit, type PlaygroundKitHints } from "./enrichKitControls";
+import {
+  componentAcceptsChildren,
+  controlsForSpec,
+  ensureChildrenControl,
+} from "./controls";
+import { genericUsageSnippet } from "./snippet";
+import { mergeStaticDefaults, normalizedPropKinds, valuesToComponentProps } from "./propCoerce";
+
+function isDefinedPlayground(value: unknown): value is import("./definePlayground").DefinedPlayground {
+  if (!value || typeof value !== "object") return false;
+  const o = value as Record<string, unknown>;
+  if (typeof o.playgroundMeta !== "object" || o.playgroundMeta === null) return false;
+  const meta = o.playgroundMeta as { id?: unknown; title?: unknown; group?: unknown };
+  return (
+    typeof meta.id === "string" &&
+    typeof meta.title === "string" &&
+    (meta.group === undefined || typeof meta.group === "string") &&
+    Array.isArray(o.playgroundControls) &&
+    typeof o.PlaygroundPreview === "function"
+  );
+}
+
+function specForCatalogEntry(
+  report: WorkspaceReport,
+  catalogId: string,
+): PlaygroundSpec | undefined {
+  return report.playgrounds?.find(
+    (spec) => spec.export_name === catalogId || spec.id === catalogId,
+  );
+}
+
+/** When JSX inference fails, still merge CVA props whose keys match kit control params. */
+function fallbackRootPropBindings(
+  entry: PlaygroundEntry,
+  hints: PlaygroundKitHints | undefined,
+  report: WorkspaceReport,
+): PlaygroundKitHints["rootPropBindings"] {
+  const fromKit = hints?.rootPropBindings ?? [];
+  if (fromKit.length > 0) return fromKit;
+
+  const spec = specForCatalogEntry(report, entry.id);
+  if (!spec) return [];
+
+  const paramKeys = new Set(entry.controls.map((control) => control.key));
+  return (spec.declared_props ?? [])
+    .filter((prop) => paramKeys.has(prop))
+    .map((prop) => ({ component: spec.export_name, prop, param: prop }));
+}
+
+function enrichManualEntriesFromReport(
+  entries: PlaygroundEntry[],
+  modules: BuildPlaygroundModules,
+  report: WorkspaceReport | null | undefined,
+): PlaygroundEntry[] {
+  if (!report) return entries;
+
+  const definedById = new Map<string, import("./definePlayground").DefinedPlayground>();
+  for (const mod of Object.values(modules)) {
+    if (!mod || typeof mod !== "object") continue;
+    for (const [exportName, value] of Object.entries(mod)) {
+      if (!isDefinedPlayground(value)) continue;
+      const catalogId =
+        value.playgroundMeta.id || catalogIdFromPlaygroundExport(exportName) || "";
+      if (!catalogId) continue;
+      definedById.set(catalogId, value);
+    }
+  }
+
+  return entries.map((entry) => {
+    const defined = definedById.get(entry.id);
+    const bindings = fallbackRootPropBindings(
+      entry,
+      defined?.playgroundKitHints,
+      report,
+    );
+    if (!bindings.length) return entry;
+    const controls = mergeReportControlsForKit(entry.controls, bindings, report, entry.id);
+    return controls === entry.controls ? entry : { ...entry, controls };
+  });
+}
 
 export type BuildPlaygroundModules = Record<string, Record<string, unknown>>;
 
@@ -16,7 +111,7 @@ export type BuildPlaygroundOptions = {
   globKeyFromRelPath?: (relPath: string) => string;
   controlOverrides?: Record<string, PlaygroundControl[]>;
   staticDefaults?: Record<string, Record<string, unknown>>;
-  /** When true (default in Vite dev), log specs that failed to join to `modules`. */
+  /** When true, log specs that failed to join to `modules` (inspect pane still shows skips). */
   logJoinSkips?: boolean;
 };
 
@@ -25,8 +120,11 @@ export type BuildPlaygroundResult = {
   skipped: PlaygroundJoinSkip[];
 };
 
-function defaultGlobKeyFromRelPath(relPath: string): string {
-  return defaultEmbedGlobKeyFromRelPath(relPath);
+function usageForExportName(
+  report: WorkspaceReport | null | undefined,
+  exportName: string,
+): UsageSummary | undefined {
+  return report?.usage_by_component?.find((u) => u.component === exportName);
 }
 
 export type { PlaygroundJoinSkip, PlaygroundJoinSkipReason } from "./playgroundJoin";
@@ -40,248 +138,6 @@ export {
   logPlaygroundJoinSkips,
 } from "./playgroundJoin";
 
-function coerceDeclaredPropKind(v: unknown): DeclaredPropKind | undefined {
-  if (v === "boolean" || v === "string" || v === "number" || v === "unknown")
-    return v;
-  return undefined;
-}
-
-function normalizedPropKinds(
-  raw: PlaygroundSpec["declared_prop_kinds"],
-): Partial<Record<string, DeclaredPropKind>> | undefined {
-  if (!raw || typeof raw !== "object") return undefined;
-  const out: Partial<Record<string, DeclaredPropKind>> = {};
-  for (const [k, v] of Object.entries(raw as Record<string, unknown>)) {
-    const ck = coerceDeclaredPropKind(v);
-    if (ck && ck !== "unknown") out[k] = ck;
-  }
-  return Object.keys(out).length ? out : undefined;
-}
-
-function isLikelyBooleanProp(name: string): boolean {
-  const n = name.toLowerCase();
-  if (n === "disabled" || n === "loading") return true;
-  if (n.startsWith("is") || n.startsWith("has")) return true;
-  if (n.startsWith("show") || n.startsWith("hide")) return true;
-  return false;
-}
-
-function defaultStringForProp(key: string): string {
-  if (key === "href") return "#!/governance";
-  const k = key.toLowerCase();
-  if (
-    k === "title" ||
-    k === "label" ||
-    k === "text" ||
-    k === "name" ||
-    k === "heading"
-  ) {
-    return "Label";
-  }
-  return key;
-}
-
-function controlsFromDeclaredProps(
-  declaredProps: string[],
-  propKinds?: Partial<Record<string, DeclaredPropKind>>,
-): PlaygroundControl[] {
-  const skip = new Set(["key", "ref"]);
-  const out: PlaygroundControl[] = [];
-  for (const key of declaredProps) {
-    if (skip.has(key)) continue;
-    if (key === "children") {
-      out.push({
-        key: "children",
-        label: "children",
-        type: "string",
-        default: "",
-        placeholder: "Preview if empty",
-      });
-      continue;
-    }
-    const kind = propKinds?.[key];
-    if (kind === "boolean") {
-      out.push({ key, label: key, type: "boolean", default: false });
-    } else if (kind === "number") {
-      out.push({ key, label: key, type: "number", default: 0 });
-    } else if (kind === "string") {
-      out.push({
-        key,
-        label: key,
-        type: "string",
-        default: defaultStringForProp(key),
-        placeholder: key,
-      });
-    } else if (isLikelyBooleanProp(key)) {
-      out.push({ key, label: key, type: "boolean", default: false });
-    } else {
-      out.push({
-        key,
-        label: key,
-        type: "string",
-        default: defaultStringForProp(key),
-        placeholder: key,
-      });
-    }
-  }
-  return out;
-}
-
-function controlsForSpec(
-  catalogId: string,
-  declaredProps: string[],
-  propKinds: Partial<Record<string, DeclaredPropKind>> | undefined,
-  controlOverrides: Record<string, PlaygroundControl[]>,
-): PlaygroundControl[] {
-  const override = controlOverrides[catalogId];
-  if (override) return override;
-  return controlsFromDeclaredProps(declaredProps, propKinds);
-}
-
-function valuesToComponentProps(
-  declaredProps: string[],
-  values: PlaygroundArgs,
-  propKinds?: Partial<Record<string, DeclaredPropKind>>,
-): Record<string, unknown> {
-  const o: Record<string, unknown> = {};
-  for (const key of declaredProps) {
-    if (key === "key" || key === "ref") continue;
-    if (key === "children") {
-      const v = values.children;
-      o[key] =
-        v !== undefined && v !== null && String(v).length > 0
-          ? String(v)
-          : "Preview";
-      continue;
-    }
-    const kind = propKinds?.[key];
-    if (kind === "boolean") {
-      o[key] = Boolean(values[key]);
-      continue;
-    }
-    if (kind === "number") {
-      const raw = values[key];
-      const n = typeof raw === "number" ? raw : Number(raw);
-      o[key] = Number.isFinite(n) ? n : 0;
-      continue;
-    }
-    if (kind === "string") {
-      o[key] = values[key];
-      continue;
-    }
-    if (isLikelyBooleanProp(key)) {
-      o[key] = Boolean(values[key]);
-      continue;
-    }
-    o[key] = values[key];
-  }
-  return o;
-}
-
-function mergeStaticDefaults(
-  fromValues: Record<string, unknown>,
-  staticDefaults: Record<string, unknown>,
-): Record<string, unknown> {
-  const o = { ...fromValues };
-  for (const [k, v] of Object.entries(staticDefaults)) {
-    const cur = o[k];
-    if (cur === undefined || cur === "") o[k] = v;
-  }
-  return o;
-}
-
-function getExport(
-  mod: Record<string, unknown>,
-  exportName: string,
-): ComponentType<Record<string, unknown>> | undefined {
-  const x = mod[exportName];
-  if (typeof x === "function")
-    return x as ComponentType<Record<string, unknown>>;
-  return undefined;
-}
-
-function jsxTextOrStringifyExpression(text: string): string {
-  if (!/[<>{}&]/.test(text)) return text;
-  return `{JSON.stringify(${JSON.stringify(text)})}`;
-}
-
-function valueMatchesPlaygroundDefault(
-  control: PlaygroundControl,
-  value: string | number | boolean | undefined,
-): boolean {
-  switch (control.type) {
-    case "boolean":
-      return Boolean(value) === control.default;
-    case "number": {
-      const n = typeof value === "number" ? value : Number(value);
-      return Number.isFinite(n) && n === control.default;
-    }
-    case "string":
-    case "select":
-      return String(value ?? "") === String(control.default);
-    default:
-      return false;
-  }
-}
-
-function genericUsageSnippet(
-  exportName: string,
-  values: PlaygroundArgs,
-  controls: PlaygroundControl[],
-): string {
-  const controlByKey = new Map(controls.map((c) => [c.key, c] as const));
-
-  const emitPropKey = (key: string): boolean => {
-    const c = controlByKey.get(key);
-    if (!c) return true;
-    return !valueMatchesPlaygroundDefault(c, values[key]);
-  };
-
-  const hasChildrenKey = Object.prototype.hasOwnProperty.call(
-    values,
-    "children",
-  );
-  const childVal = hasChildrenKey ? values.children : undefined;
-
-  const propKeys = Object.keys(values)
-    .filter((k) => k !== "children")
-    .filter(emitPropKey)
-    .sort((a, b) => a.localeCompare(b));
-  const propsStr = propKeys
-    .map((k) => `${k}={${JSON.stringify(values[k])}}`)
-    .join(" ");
-
-  const openWithProps =
-    propKeys.length === 0 ? `<${exportName}` : `<${exportName} ${propsStr}`;
-
-  if (!hasChildrenKey) {
-    return propKeys.length === 0 ? `<${exportName} />` : `${openWithProps} />`;
-  }
-
-  if (typeof childVal === "boolean") {
-    const allKeys = Object.keys(values)
-      .filter(emitPropKey)
-      .sort((a, b) => a.localeCompare(b));
-    const allProps = allKeys
-      .map((k) => `${k}={${JSON.stringify(values[k])}}`)
-      .join(" ");
-    return allKeys.length === 0
-      ? `<${exportName} />`
-      : `<${exportName} ${allProps} />`;
-  }
-
-  const asText =
-    typeof childVal === "number" ? String(childVal) : String(childVal ?? "");
-  if (asText.length === 0) {
-    return propKeys.length === 0 ? `<${exportName} />` : `${openWithProps} />`;
-  }
-
-  const body = jsxTextOrStringifyExpression(asText);
-  return propKeys.length === 0
-    ? `<${exportName}>${body}</${exportName}>`
-    : `${openWithProps}>${body}</${exportName}>`;
-}
-
 /** Sidebar / URL id — matches catalog component names (`export_name`). */
 export function playgroundCatalogId(spec: PlaygroundSpec): string {
   return spec.export_name;
@@ -310,47 +166,69 @@ export function buildPlaygroundEntriesFromReportWithSkips(
   options: BuildPlaygroundOptions = {},
 ): BuildPlaygroundResult {
   const specs = report?.playgrounds;
-  if (!specs?.length) return { entries: [], skipped: [] };
-
   const globKeyFromRelPath =
-    options.globKeyFromRelPath ?? defaultGlobKeyFromRelPath;
+    options.globKeyFromRelPath ?? defaultEmbedGlobKeyFromRelPath;
   const controlOverrides = options.controlOverrides ?? {};
   const staticDefaultsMap = options.staticDefaults ?? {};
 
-  const skipped = diagnosePlaygroundJoinSkips(report, modules, {
-    globKeyFromRelPath,
-  });
-  const shouldLog =
-    options.logJoinSkips ??
-    (typeof import.meta !== "undefined" && Boolean(import.meta.env?.DEV));
-  if (shouldLog) logPlaygroundJoinSkips(skipped);
+  const skipped = specs?.length
+    ? diagnosePlaygroundJoinSkips(report, modules, {
+        globKeyFromRelPath,
+      })
+    : [];
+  if (options.logJoinSkips) logPlaygroundJoinSkips(skipped);
+
+  const autoEntries: PlaygroundEntry[] = [];
+  if (!specs?.length) {
+    const manualOnly = enrichManualEntriesFromReport(
+      collectDefinedPlaygrounds(modules),
+      modules,
+      report,
+    );
+    return { entries: mergePlaygroundEntries([], manualOnly), skipped };
+  }
 
-  const out: PlaygroundEntry[] = [];
   for (const spec of specs) {
     const globKey = globKeyFromRelPath(spec.rel_path);
-    const mod = modules[globKey];
+    const resolvedKey = resolveModuleKeyForRelPath(spec.rel_path, modules, globKeyFromRelPath);
+    const mod = resolvedKey ? modules[resolvedKey] : undefined;
     if (!mod) continue;
-    const Cmp = getExport(mod, spec.export_name);
+    const Cmp = getModuleExport(mod, spec.export_name);
     if (!Cmp) continue;
 
     const catalogId = playgroundCatalogId(spec);
     const declared = spec.declared_props ?? [];
     const propKinds = normalizedPropKinds(spec.declared_prop_kinds);
-    const controls = controlsForSpec(
-      catalogId,
-      declared,
-      propKinds,
-      controlOverrides,
+    const repoUsage = usageForExportName(report, spec.export_name);
+    const controls = ensureChildrenControl(
+      controlsForSpec(
+        catalogId,
+        declared,
+        propKinds,
+        spec.declared_prop_options,
+        spec.declared_prop_defaults,
+        controlOverrides,
+        spec.export_name,
+      ),
+      componentAcceptsChildren(declared, repoUsage),
+      spec.export_name,
     );
-    const staticDefaults =
-      staticDefaultsMap[catalogId] ??
-      staticDefaultsMap[spec.id] ??
-      {};
-
-    function Preview({ values }: { values: PlaygroundArgs }) {
-      const fromValues = valuesToComponentProps(declared, values, propKinds);
+    const staticDefaults = staticDefaultsMap[catalogId] ?? staticDefaultsMap[spec.id] ?? {};
+
+    const renderPreview = (values: PlaygroundArgs) => {
+      const fromValues = valuesToComponentProps(
+        controls,
+        declared,
+        values,
+        propKinds,
+        spec.export_name,
+      );
       const merged = mergeStaticDefaults(fromValues, staticDefaults);
       return createElement(Cmp, merged);
+    };
+
+    function Preview({ values }: { values: PlaygroundArgs }) {
+      return renderPreview(values);
     }
 
     const meta: PlaygroundMeta = {
@@ -359,24 +237,68 @@ export function buildPlaygroundEntriesFromReportWithSkips(
       ...(spec.group ? { group: spec.group } : {}),
     };
 
-    out.push({
+    autoEntries.push({
       id: catalogId,
       meta,
-      modulePath: globKey,
+      modulePath: resolvedKey ?? globKey,
       controls,
-      usageSnippet: (values) =>
-        genericUsageSnippet(spec.export_name, values, controls),
+      usageSnippet: (values) => genericUsageSnippet(spec.export_name, values, controls),
+      renderPreview,
       Preview: Preview as PlaygroundPreviewComponent,
     });
   }
 
-  out.sort((a, b) => {
-    const ga = a.meta.group ?? "";
-    const gb = b.meta.group ?? "";
-    if (ga !== gb) return ga.localeCompare(gb);
-    return a.meta.title.localeCompare(b.meta.title);
+  if (report) {
+    upgradeRootEntriesWithCompoundPreview(autoEntries, report, modules, {
+      globKeyFromRelPath,
+      controlOverrides,
+      staticDefaults: staticDefaultsMap,
+    });
+  }
+
+  const compoundEntries = buildCompoundPlaygroundEntries(report, modules, {
+    globKeyFromRelPath,
+    controlOverrides,
+    staticDefaults: staticDefaultsMap,
+    existingIds: new Set(autoEntries.map((entry) => entry.id)),
   });
-  return { entries: out, skipped };
+  const manualEntries = enrichManualEntriesFromReport(
+    collectDefinedPlaygrounds(modules),
+    modules,
+    report,
+  );
+  const merged = mergePlaygroundEntries(
+    [...autoEntries, ...compoundEntries],
+    manualEntries,
+  );
+  return {
+    entries: filterCatalogVisiblePlaygroundEntries(report, merged),
+    skipped,
+  };
+}
+
+function entryPathsForCatalog(
+  report: WorkspaceReport | null | undefined,
+  entry: PlaygroundEntry,
+): string[] {
+  if (!report) return [entry.modulePath];
+  const fromReport = definitionPathsForName(report, entry.meta.id);
+  return fromReport.length > 0 ? fromReport : [entry.modulePath];
+}
+
+function filterCatalogVisiblePlaygroundEntries(
+  report: WorkspaceReport | null | undefined,
+  entries: PlaygroundEntry[],
+): PlaygroundEntry[] {
+  if (!report) return entries;
+  return entries.filter(
+    (entry) =>
+      !isCatalogComponentHidden(
+        entry.meta.id,
+        report,
+        entryPathsForCatalog(report, entry),
+      ),
+  );
 }
 
 /** Build playground entries from report specs + eager Vite modules. */
@@ -385,6 +307,5 @@ export function buildPlaygroundEntriesFromReport(
   modules: BuildPlaygroundModules,
   options: BuildPlaygroundOptions = {},
 ): PlaygroundEntry[] {
-  return buildPlaygroundEntriesFromReportWithSkips(report, modules, options)
-    .entries;
+  return buildPlaygroundEntriesFromReportWithSkips(report, modules, options).entries;
 }

package/src/playground/catalogIdFromPlaygroundExport.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, it } from "vitest";
+import { catalogIdFromPlaygroundExport } from "./catalogIdFromPlaygroundExport";
+
+describe("catalogIdFromPlaygroundExport", () => {
+  it("maps *Playground export names to PascalCase catalog ids", () => {
+    expect(catalogIdFromPlaygroundExport("alertPlayground")).toBe("Alert");
+    expect(catalogIdFromPlaygroundExport("toggleGroupPlayground")).toBe("ToggleGroup");
+    expect(catalogIdFromPlaygroundExport("dropdownMenuPlayground")).toBe("DropdownMenu");
+  });
+
+  it("returns undefined for non-playground export names", () => {
+    expect(catalogIdFromPlaygroundExport("Alert")).toBeUndefined();
+    expect(catalogIdFromPlaygroundExport("playground")).toBeUndefined();
+  });
+});

package/src/playground/catalogIdFromPlaygroundExport.ts

@@ -0,0 +1,8 @@
+/** `alertPlayground` → `Alert`, `toggleGroupPlayground` → `ToggleGroup`. */
+export function catalogIdFromPlaygroundExport(exportName: string): string | undefined {
+  const match = /^(.+)Playground$/.exec(exportName);
+  if (!match) return undefined;
+  const stem = match[1];
+  if (!stem) return undefined;
+  return stem.charAt(0).toUpperCase() + stem.slice(1);
+}

package/src/playground/collectDefinedPlaygrounds.test.ts

@@ -0,0 +1,59 @@
+import { createElement } from "react";
+import { describe, expect, it } from "vitest";
+import { definePlayground } from "./definePlayground";
+import { collectDefinedPlaygrounds } from "./collectDefinedPlaygrounds";
+
+describe("collectDefinedPlaygrounds", () => {
+  it("collects definePlayground exports from eager modules", () => {
+    const defined = definePlayground(
+      () => createElement("span", null, "menu"),
+      { id: "DropdownMenu", group: "ui" },
+    );
+    const modules = {
+      "../components/ui/dropdown-menu.playground.tsx": {
+        dropdownMenuPlayground: defined,
+        unrelated: 42,
+      },
+    };
+    const entries = collectDefinedPlaygrounds(modules);
+    expect(entries).toHaveLength(1);
+    expect(entries[0]?.id).toBe("DropdownMenu");
+    expect(entries[0]?.meta.group).toBe("ui");
+    expect(entries[0]?.controls).toEqual([]);
+  });
+
+  it("ignores modules without definePlayground exports", () => {
+    const modules = {
+      "../components/ui/button.tsx": {
+        Button: () => createElement("button"),
+      },
+    };
+    expect(collectDefinedPlaygrounds(modules)).toEqual([]);
+  });
+
+  it("infers catalog id from *Playground export name when id is omitted", () => {
+    const defined = definePlayground(() => createElement("span", null, "alert"));
+    const modules = {
+      "../components/ui/alert.playground.tsx": {
+        alertPlayground: defined,
+      },
+    };
+    const entries = collectDefinedPlaygrounds(modules);
+    expect(entries).toHaveLength(1);
+    expect(entries[0]?.id).toBe("Alert");
+    expect(entries[0]?.meta.title).toBe("Alert");
+  });
+
+  it("ignores malformed definePlayground-like exports", () => {
+    const modules = {
+      "../components/ui/dropdown-menu.playground.tsx": {
+        invalid: {
+          playgroundMeta: { id: "DropdownMenu", title: 123 },
+          playgroundControls: [],
+          PlaygroundPreview: () => createElement("span", null, "menu"),
+        },
+      },
+    };
+    expect(collectDefinedPlaygrounds(modules)).toEqual([]);
+  });
+});