dslinter 0.1.5 → 0.2.0

package/src/playground/usePlaygroundFromReport.test.ts

@@ -1,11 +1,11 @@
 import { describe, expect, it } from "vitest";
 import { embedGlobKeyFromRelPath } from "../../vite/collectScanModules";
+import type { WorkspaceReport } from "../types/report";
 import { buildPlaygroundEntriesFromReportWithSkips } from "./buildPlaygroundEntriesFromReport";
 
 describe("autoPlayground join (embed glob keys)", () => {
   it("joins report playgrounds to virtual module keys", () => {
-    const relPath =
-      "resources/js/Components/Billing/AdditionalEventLimitModal.tsx";
+    const relPath = "resources/js/Components/Billing/AdditionalEventLimitModal.tsx";
     const globKey = embedGlobKeyFromRelPath(relPath);
     const modules = {
       [globKey]: {
@@ -14,21 +14,31 @@ describe("autoPlayground join (embed glob keys)", () => {
         },
       },
     };
-    const report = {
+    const report: WorkspaceReport = {
+      root: "/repo",
+      files: [],
+      findings: [],
+      duplicate_components: [],
+      usage_by_component: [],
+      scores: {
+        design_system_health: 0,
+        ux_consistency: 0,
+        accessibility: 0,
+        maintainability: 0,
+      },
       playgrounds: [
         {
           id: "AdditionalEventLimitModal",
           export_name: "AdditionalEventLimitModal",
           rel_path: relPath,
+          declared_props: [],
         },
       ],
     };
 
-    const { entries, skipped } = buildPlaygroundEntriesFromReportWithSkips(
-      report,
-      modules,
-      { logJoinSkips: false },
-    );
+    const { entries, skipped } = buildPlaygroundEntriesFromReportWithSkips(report, modules, {
+      logJoinSkips: false,
+    });
 
     expect(skipped).toHaveLength(0);
     expect(entries).toHaveLength(1);

package/src/playground/usePlaygroundFromReport.ts

@@ -2,6 +2,7 @@ import { useMemo } from "react";
 import type { WorkspaceReport } from "../types/report";
 import { buildPlaygroundEntriesFromReportWithSkips } from "./buildPlaygroundEntriesFromReport";
 import type { BuildPlaygroundResult } from "./buildPlaygroundEntriesFromReport";
+import { playgroundSpecsKey } from "./playgroundSpecsKey";
 import { scanPlaygroundModules } from "./scanPlaygroundModules";
 
 /**
@@ -12,12 +13,13 @@ import { scanPlaygroundModules } from "./scanPlaygroundModules";
 export function usePlaygroundFromReport(
   report: WorkspaceReport | null | undefined,
 ): BuildPlaygroundResult {
+  const specsKey = playgroundSpecsKey(report);
   return useMemo(
     () =>
       buildPlaygroundEntriesFromReportWithSkips(
         report,
         scanPlaygroundModules,
       ),
-    [report],
+    [specsKey],
   );
 }

package/src/report/a11yForModule.ts

@@ -1,4 +1,5 @@
 import type { LintFinding, WorkspaceReport } from "../types/report";
+import { a11yScoreFromFindings } from "./a11yScoring";
 import { pathsMatch, resolveModuleSourcePath } from "./modulePathMatch";
 
 export type A11yModuleSummary = {
@@ -23,13 +24,7 @@ export function a11ySummaryForModule(
   const all = report.findings.filter((f) => f.rule_id.startsWith("a11y-"));
   const findings = all.filter((f) => pathsMatch(f.path, target));
 
-  let penalty = 0;
-  for (const f of findings) {
-    if (f.severity === "error") penalty += 25;
-    else if (f.severity === "warning") penalty += 10;
-    else penalty += 3;
-  }
-  const score = Math.max(0, Math.min(100, Math.round(100 - penalty)));
+  const score = a11yScoreFromFindings(findings);
 
   return { score, issueCount: findings.length, findings };
 }

package/src/report/a11yScoring.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from "vitest";
+import { a11yScoreFromFindings } from "./a11yScoring";
+
+describe("a11yScoreFromFindings", () => {
+  it("starts at 100 with no findings", () => {
+    expect(a11yScoreFromFindings([])).toBe(100);
+  });
+
+  it("applies severity penalties", () => {
+    expect(
+      a11yScoreFromFindings([
+        { severity: "error" },
+        { severity: "warning" },
+        { severity: "info" },
+      ]),
+    ).toBe(62);
+  });
+
+  it("never drops below zero", () => {
+    expect(
+      a11yScoreFromFindings(Array.from({ length: 10 }, () => ({ severity: "error" as const }))),
+    ).toBe(0);
+  });
+});

package/src/report/a11yScoring.ts

@@ -0,0 +1,17 @@
+import type { Severity } from "../types/report";
+
+export function a11yScoreFromSeverities(severities: Severity[]): number {
+  let penalty = 0;
+  for (const severity of severities) {
+    if (severity === "error") penalty += 25;
+    else if (severity === "warning") penalty += 10;
+    else penalty += 3;
+  }
+  return Math.max(0, Math.min(100, Math.round(100 - penalty)));
+}
+
+export function a11yScoreFromFindings(
+  findings: ReadonlyArray<{ severity: Severity }>,
+): number {
+  return a11yScoreFromSeverities(findings.map((f) => f.severity));
+}

package/src/report/index.ts

@@ -0,0 +1,6 @@
+export type { A11yModuleSummary } from "./a11yForModule";
+export { a11ySummaryForModule, resolveModuleSourcePath } from "./a11yForModule";
+export type { CodeScoreModuleSummary } from "./codeScoreForModule";
+export { codeScoreSummaryForModule } from "./codeScoreForModule";
+export { tokenStyleFindingsForModule } from "./tokenStyleFindingsForModule";
+export { findingsForComponent } from "./findingsForComponent";

package/src/shell/DashboardLayout.tsx

@@ -12,15 +12,17 @@ import {
 import type { PlaygroundEntry } from "../types/playground";
 import type { TokenCatalog } from "../types/tokenCatalog";
 import type { DslinterReportState } from "../dashboard/useWorkspaceReport";
-import { Button } from "../components/ui/button";
-import { cn } from "../lib/utils";
 import { ComponentInspectPane } from "../components/ComponentInspectPane";
 import { ComponentPlaygroundPane } from "../components/ComponentPlaygroundPane";
 import { GovernancePane } from "../components/GovernancePane";
 import { Sidebar } from "../components/Sidebar";
 import { TokensPane } from "../components/TokensPane";
 import { DashboardCommandPalette } from "../components/DashboardCommandPalette";
-import { componentCatalogNamesFromReport } from "../dashboard/aggregate";
+import {
+  componentCatalogNamesFromReport,
+  componentCatalogTreeFromReport,
+} from "../dashboard/aggregate";
+import { reportWithExtraHidden } from "../dashboard/catalogVisibility";
 import { resolvePlaygroundEntry } from "../playground/buildPlaygroundEntriesFromReport";
 import {
   findPlaygroundJoinSkip,
@@ -48,13 +50,10 @@ function readStored(): DashboardThemePreference | null {
       }
     }
     if (v === "light" || v === "dark") return v;
-    /** Migrate legacy `system` (and any unknown) to an explicit mode. */
-    if (v === "system") {
-      const next = window.matchMedia("(prefers-color-scheme: dark)").matches
-        ? "dark"
-        : "light";
-      localStorage.setItem(STORAGE_KEY, next);
-      return next;
+    /** Migrate legacy `system` (and any unknown) — OS preference is ignored. */
+    if (v != null) {
+      localStorage.setItem(STORAGE_KEY, "light");
+      return "light";
     }
   } catch {
     /* ignore */
@@ -139,14 +138,12 @@ export type DashboardLayoutProps = {
   /** Join failures from `buildPlaygroundEntriesFromReportWithSkips` — powers inspect-pane hints. */
   playgroundJoinSkips?: PlaygroundJoinSkip[];
   tokenCatalog?: TokenCatalog;
-  /** Custom intro shown above the governance inventory on `#!/governance`; defaults to package copy. */
+  /** Custom intro shown above the governance inventory on `/governance`; defaults to package copy. */
   overview?: ReactNode;
   /** Fetch URL for `dslint --json` output. */
   reportUrl?: string;
   /** Shown next to the governance refresh hint. */
   dslinterReportHint?: string;
-  /** Maps Vite `import.meta.glob` path to a label in the component header. */
-  formatModulePath?: (modulePath: string) => string;
   /** Workspace report fetch state (shared by governance + component a11y). */
   dslinterReport: DslinterReportState;
 };
@@ -166,16 +163,48 @@ export function DashboardLayoutInner({
   overview,
   reportUrl,
   dslinterReportHint,
-  formatModulePath,
   dslinterReport,
 }: DashboardLayoutInnerProps) {
   const [route, navigate] = useHashRoute();
   const [commandPaletteOpen, setCommandPaletteOpen] = useState(false);
+  const [optimisticHidden, setOptimisticHidden] = useState<string[]>([]);
   const { theme, setTheme, resolvedTheme } = useDashboardTheme();
 
+  const catalogReport = useMemo(
+    () => reportWithExtraHidden(dslinterReport.report, optimisticHidden),
+    [dslinterReport.report, optimisticHidden],
+  );
+
   const catalogNames = useMemo(
-    () => componentCatalogNamesFromReport(dslinterReport.report),
-    [dslinterReport.report],
+    () => componentCatalogNamesFromReport(catalogReport),
+    [catalogReport],
+  );
+  const catalogEntries = useMemo(() => {
+    const tree = componentCatalogTreeFromReport(catalogReport);
+    return tree.flatMap((item) => {
+      if (item.type === "component") {
+        return [{ name: item.name, label: item.name }];
+      }
+      return [
+        { name: item.parent, label: item.parent },
+        ...item.children.map((child) => ({
+          name: child,
+          label: `${item.parent} / ${child}`,
+        })),
+      ];
+    });
+  }, [catalogReport]);
+
+  const handleHideFromCatalog = useCallback(
+    (componentName: string) => {
+      setOptimisticHidden((prev) =>
+        prev.includes(componentName) ? prev : [...prev, componentName],
+      );
+      if (route.view === "component" && route.componentId === componentName) {
+        navigate({ view: "governance" });
+      }
+    },
+    [route, navigate],
   );
 
   const reportReady =
@@ -216,9 +245,12 @@ export function DashboardLayoutInner({
       main = (
         <ComponentPlaygroundPane
           entry={entry}
-          formatModulePath={formatModulePath}
           workspaceReport={dslinterReport.report}
           reportReady={reportReady}
+          onOpenComponent={(name) =>
+            navigate({ view: "component", componentId: name })
+          }
+          onHideFromCatalog={handleHideFromCatalog}
         />
       );
     } else if (inCatalog) {
@@ -233,23 +265,22 @@ export function DashboardLayoutInner({
             componentId,
           )}
           onBackToGovernance={() => navigate({ view: "governance" })}
+          onOpenComponent={(name) =>
+            navigate({ view: "component", componentId: name })
+          }
+          onHideFromCatalog={handleHideFromCatalog}
         />
       );
     } else {
       main = (
         <div className="flex min-h-0 flex-1 flex-col items-center justify-center gap-3 bg-muted/40 px-8 text-center">
-          <p className="text-sm font-medium text-foreground">Unknown component</p>
+          <p className="text-sm font-medium text-foreground">
+            Unknown component
+          </p>
           <p className="max-w-md text-xs text-muted-foreground">
             <span className="font-mono">{componentId}</span> is not in the
             latest scan catalog.
           </p>
-          <Button
-            type="button"
-            size="sm"
-            onClick={() => navigate({ view: "governance" })}
-          >
-            Back to governance
-          </Button>
         </div>
       );
     }
@@ -257,19 +288,17 @@ export function DashboardLayoutInner({
 
   return (
     <div
-      className={cn(
-        "flex h-screen min-h-0 bg-background text-foreground",
-        resolvedTheme === "dark" && "dark",
-      )}
+      data-dashboard-theme={resolvedTheme}
+      className="flex h-screen min-h-0 bg-background text-foreground"
     >
       <DashboardCommandPalette
-        catalogNames={catalogNames}
+        catalogEntries={catalogEntries}
         onNavigate={navigate}
         open={commandPaletteOpen}
         onOpenChange={setCommandPaletteOpen}
       />
       <Sidebar
-        report={dslinterReport.report}
+        report={catalogReport ?? null}
         reportLoading={dslinterReport.loading}
         reportError={dslinterReport.error}
         route={route}
@@ -277,6 +306,7 @@ export function DashboardLayoutInner({
         onOpenCommandPalette={() => setCommandPaletteOpen(true)}
         theme={theme}
         onThemeChange={setTheme}
+        catalogNames={catalogNames}
       />
       <div className="ml-[240px] flex min-h-0 min-w-0 flex-1 flex-col">
         {main}
@@ -286,23 +316,19 @@ export function DashboardLayoutInner({
 }
 
 export function DashboardLayout(props: DashboardLayoutProps) {
-  if (props.autoPlayground) {
-    return (
-      <DashboardThemeProvider>
+  return (
+    <DashboardThemeProvider>
+      {props.autoPlayground ? (
         <Suspense fallback={null}>
           <DashboardLayoutAuto {...props} />
         </Suspense>
-      </DashboardThemeProvider>
-    );
-  }
-
-  return (
-    <DashboardThemeProvider>
-      <DashboardLayoutInner
-        {...props}
-        playgroundEntries={props.playgroundEntries ?? []}
-        playgroundJoinSkips={props.playgroundJoinSkips}
-      />
+      ) : (
+        <DashboardLayoutInner
+          {...props}
+          playgroundEntries={props.playgroundEntries ?? []}
+          playgroundJoinSkips={props.playgroundJoinSkips}
+        />
+      )}
     </DashboardThemeProvider>
   );
 }

package/src/shell/DashboardLayoutAuto.tsx

@@ -11,10 +11,6 @@ export default function DashboardLayoutAuto(props: DashboardLayoutProps) {
       {...props}
       playgroundEntries={autoPlaygroundBuild.entries}
       playgroundJoinSkips={autoPlaygroundBuild.skipped}
-      formatModulePath={
-        props.formatModulePath ??
-        ((modulePath: string) => modulePath.replace(/^@dslint-scan\//, ""))
-      }
     />
   );
 }

package/src/shell/hashRoute.test.ts

@@ -3,26 +3,20 @@ import { formatHashRoute, parseHashRoute } from "./hashRoute";
 
 describe("parseHashRoute", () => {
   it("parses governance overview", () => {
-    expect(parseHashRoute("#!/governance")).toEqual({ view: "governance" });
+    expect(parseHashRoute("/governance")).toEqual({ view: "governance" });
+    expect(parseHashRoute("/")).toEqual({ view: "governance" });
     expect(parseHashRoute("")).toEqual({ view: "governance" });
   });
 
-  it("parses legacy governance catalog deep link as component route", () => {
-    expect(parseHashRoute("#!/governance/ActionItem")).toEqual({
-      view: "component",
-      componentId: "ActionItem",
-    });
-  });
-
   it("parses component route", () => {
-    expect(parseHashRoute("#!/component/ActionItem")).toEqual({
+    expect(parseHashRoute("/component/ActionItem")).toEqual({
       view: "component",
       componentId: "ActionItem",
     });
   });
 
   it("parses tokens", () => {
-    expect(parseHashRoute("#!/tokens")).toEqual({ view: "tokens" });
+    expect(parseHashRoute("/tokens")).toEqual({ view: "tokens" });
   });
 });
 
@@ -30,12 +24,10 @@ describe("formatHashRoute", () => {
   it("formats component route", () => {
     expect(
       formatHashRoute({ view: "component", componentId: "ActionItem" }),
-    ).toBe("#!/component/ActionItem");
+    ).toBe("/component/ActionItem");
   });
 
-  it("formats governance catalog", () => {
-    expect(
-      formatHashRoute({ view: "governance", catalog: "ActionItem" }),
-    ).toBe("#!/governance/ActionItem");
+  it("formats governance", () => {
+    expect(formatHashRoute({ view: "governance" })).toBe("/governance");
   });
 });

package/src/shell/hashRoute.ts

@@ -1,40 +1,34 @@
 export type HashRoute =
   | { view: "tokens" }
-  | { view: "governance"; catalog?: string }
+  | { view: "governance" }
   | { view: "component"; componentId: string };
 
-const PREFIX = "#!/";
-
-function stripShebang(hash: string): string {
-  if (hash.startsWith(PREFIX)) {
-    return hash.slice(PREFIX.length);
+function trimTrailingSlashes(path: string): string {
+  let end = path.length;
+  while (end > 1 && path[end - 1] === "/") {
+    end--;
   }
-  if (hash.startsWith("#")) {
-    return hash.slice(1);
+  return path.slice(0, end);
+}
+
+function normalizePath(input: string): string {
+  const raw = input.trim();
+  if (raw.startsWith("/")) {
+    return trimTrailingSlashes(raw);
   }
-  return hash;
+  return raw.length > 0 ? `/${raw}` : "/";
 }
 
-export function parseHashRoute(hash: string): HashRoute {
-  const raw = stripShebang(hash).trim();
-  if (raw === "" || raw === "overview") {
+export function parseHashRoute(pathname: string): HashRoute {
+  const path = normalizePath(pathname);
+  if (path === "/" || path === "/overview" || path === "/governance") {
     return { view: "governance" };
   }
-  if (raw === "tokens") {
+  if (path === "/tokens") {
     return { view: "tokens" };
   }
-  if (raw === "governance") {
-    return { view: "governance" };
-  }
-  if (raw.startsWith("governance/")) {
-    const catalog = decodeURIComponent(raw.slice("governance/".length));
-    if (catalog.length > 0) {
-      /** Legacy deep links — component pages replaced governance catalog scroll. */
-      return { view: "component", componentId: catalog };
-    }
-  }
-  if (raw.startsWith("component/")) {
-    const componentId = decodeURIComponent(raw.slice("component/".length));
+  if (path.startsWith("/component/")) {
+    const componentId = decodeURIComponent(path.slice("/component/".length));
     if (componentId.length > 0) {
       return { view: "component", componentId };
     }
@@ -45,14 +39,20 @@ export function parseHashRoute(hash: string): HashRoute {
 export function formatHashRoute(route: HashRoute): string {
   switch (route.view) {
     case "tokens":
-      return `${PREFIX}tokens`;
+      return "/tokens";
     case "governance":
-      return route.catalog
-        ? `${PREFIX}governance/${encodeURIComponent(route.catalog)}`
-        : `${PREFIX}governance`;
+      return "/governance";
     case "component":
-      return `${PREFIX}component/${encodeURIComponent(route.componentId)}`;
+      return `/component/${encodeURIComponent(route.componentId)}`;
     default:
-      return `${PREFIX}governance`;
+      return "/governance";
   }
 }
+
+/** Drop stale `#!/…` fragments left over from hash routing. */
+export function stripLegacyHashFragment(): boolean {
+  if (!window.location.hash.startsWith("#!/")) return false;
+  const clean = window.location.pathname + window.location.search;
+  window.history.replaceState(null, "", clean || "/governance");
+  return true;
+}

package/src/shell/useHashRoute.ts

@@ -1,27 +1,52 @@
-import { useCallback, useSyncExternalStore } from "react";
-import { formatHashRoute, parseHashRoute, type HashRoute } from "./hashRoute";
+import { useCallback, useEffect, useSyncExternalStore } from "react";
+import {
+  formatHashRoute,
+  parseHashRoute,
+  stripLegacyHashFragment,
+  type HashRoute,
+} from "./hashRoute";
+
+const NAVIGATE_EVENT = "dslinter:navigate";
 
 function subscribe(onStoreChange: () => void) {
-  window.addEventListener("hashchange", onStoreChange);
-  return () => window.removeEventListener("hashchange", onStoreChange);
+  window.addEventListener("popstate", onStoreChange);
+  window.addEventListener(NAVIGATE_EVENT, onStoreChange);
+  return () => {
+    window.removeEventListener("popstate", onStoreChange);
+    window.removeEventListener(NAVIGATE_EVENT, onStoreChange);
+  };
 }
 
-function getHashSnapshot() {
-  return window.location.hash || "#!/governance";
+function getPathSnapshot() {
+  return window.location.pathname || "/governance";
 }
 
-function getServerHashSnapshot() {
-  return "#!/governance";
+function getServerPathSnapshot() {
+  return "/governance";
 }
 
 export function useHashRoute(): [HashRoute, (next: HashRoute) => void] {
-  const hash = useSyncExternalStore(subscribe, getHashSnapshot, getServerHashSnapshot);
-  const route = parseHashRoute(hash);
+  const pathname = useSyncExternalStore(
+    subscribe,
+    getPathSnapshot,
+    getServerPathSnapshot,
+  );
+  const route = parseHashRoute(pathname);
+
+  useEffect(() => {
+    if (stripLegacyHashFragment()) {
+      window.dispatchEvent(new Event(NAVIGATE_EVENT));
+    }
+  }, []);
 
   const navigate = useCallback((next: HashRoute) => {
-    const nextHash = formatHashRoute(next);
-    if (nextHash !== window.location.hash) {
-      window.location.hash = nextHash;
+    const nextPath = formatHashRoute(next);
+    const pathChanged = nextPath !== window.location.pathname;
+    if (pathChanged) {
+      window.history.pushState(null, "", nextPath);
+    }
+    if (stripLegacyHashFragment() || pathChanged) {
+      window.dispatchEvent(new Event(NAVIGATE_EVENT));
     }
   }, []);
 

package/src/styles/dashboard-theme.css

@@ -2,10 +2,20 @@
  * DSLinter dashboard design tokens + shadcn/ui theme.
  * Host apps import once: `@import "dslinter/theme.css";` after `@import "tailwindcss"` and `@source` for this package.
  */
+ 
 @import "tw-animate-css";
 @import "shadcn/tailwind.css";
 
-@custom-variant dark (&:is(.dark *));
+/** Class-based dark only — never `prefers-color-scheme` or host `.dark`. */
+@custom-variant dark (&:is([data-dashboard-theme="dark"] *));
+
+html:has([data-dashboard-theme="light"]) {
+  color-scheme: only light;
+}
+
+html:has([data-dashboard-theme="dark"]) {
+  color-scheme: only dark;
+}
 
 @theme inline {
   --color-background: var(--background);
@@ -87,8 +97,9 @@
   }
 }
 
-:root {
-  color-scheme: light;
+:root,
+[data-dashboard-theme="light"] {
+  color-scheme: only light;
   --radius: 0.625rem;
   --background: oklch(1 0 0);
   --foreground: oklch(0.145 0 0);
@@ -125,8 +136,8 @@
   --sidebar-ring: oklch(0.708 0 0);
 }
 
-.dark {
-  color-scheme: dark;
+[data-dashboard-theme="dark"] {
+  color-scheme: only dark;
   --background: oklch(0.145 0 0);
   --foreground: oklch(0.985 0 0);
   --card: oklch(0.205 0 0);
@@ -178,10 +189,10 @@
     background-size: 10px 10px;
   }
 
-  .dark .ds-playground-dot-surface {
+  [data-dashboard-theme="dark"] .ds-playground-dot-surface {
     background-image: radial-gradient(
       circle,
-      rgb(148 163 184 / 0.22) 1px,
+      rgb(148 163 184 / 0.15) 1px,
       transparent 1px
     );
   }

package/src/types/controls.ts

@@ -1,11 +1,19 @@
 /** Values passed from the dashboard control panel into `PlaygroundPreview`. */
 export type PlaygroundArgs = Record<string, string | number | boolean>;
 
+export type PlaygroundValuesUpdater = (
+  next: PlaygroundArgs | ((prev: PlaygroundArgs) => PlaygroundArgs),
+) => void;
+
+/** Generated examples should not be presented as real API defaults. */
+export type PlaygroundDefaultSource = "type" | "example" | "manual";
+
 export type PlaygroundBooleanControl = {
   key: string;
   label: string;
   type: "boolean";
   default: boolean;
+  defaultSource?: PlaygroundDefaultSource;
   hint?: string;
 };
 
@@ -14,6 +22,7 @@ export type PlaygroundStringControl = {
   label: string;
   type: "string";
   default: string;
+  defaultSource?: PlaygroundDefaultSource;
   placeholder?: string;
 };
 
@@ -22,6 +31,7 @@ export type PlaygroundNumberControl = {
   label: string;
   type: "number";
   default: number;
+  defaultSource?: PlaygroundDefaultSource;
   min?: number;
   max?: number;
   step?: number;
@@ -32,6 +42,7 @@ export type PlaygroundSelectControl = {
   label: string;
   type: "select";
   default: string;
+  defaultSource?: PlaygroundDefaultSource;
   options: { value: string; label: string }[];
 };