dslinter 0.2.2 → 0.3.0

package/src/components/ScoreGauge.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from "vitest";
+import { scoreGaugeBand } from "./ScoreGauge";
+
+describe("scoreGaugeBand", () => {
+  it("returns poor for scores below 50", () => {
+    expect(scoreGaugeBand(46)).toBe("poor");
+    expect(scoreGaugeBand(0)).toBe("poor");
+    expect(scoreGaugeBand(49)).toBe("poor");
+  });
+
+  it("returns average for scores from 50 to 89", () => {
+    expect(scoreGaugeBand(75)).toBe("average");
+    expect(scoreGaugeBand(50)).toBe("average");
+    expect(scoreGaugeBand(89)).toBe("average");
+  });
+
+  it("returns good for scores 90 and above", () => {
+    expect(scoreGaugeBand(95)).toBe("good");
+    expect(scoreGaugeBand(90)).toBe("good");
+    expect(scoreGaugeBand(100)).toBe("good");
+  });
+});

package/src/components/ScoreGauge.tsx

@@ -0,0 +1,179 @@
+import type { MouseEvent } from "react";
+import { cn } from "../lib/utils";
+
+/** Score bands (0–49 poor, 50–89 average, 90–100 good). */
+export type ScoreGaugeBand = "poor" | "average" | "good";
+
+export function scoreGaugeBand(score: number): ScoreGaugeBand {
+  if (score >= 90) return "good";
+  if (score >= 50) return "average";
+  return "poor";
+}
+
+const BAND_STYLES: Record<
+  ScoreGaugeBand,
+  { stroke: string; track: string; text: string }
+> = {
+  good: {
+    stroke: "stroke-success",
+    track: "stroke-success/15",
+    text: "text-success",
+  },
+  average: {
+    stroke: "stroke-warning",
+    track: "stroke-warning/15",
+    text: "text-warning",
+  },
+  poor: {
+    stroke: "stroke-destructive",
+    track: "stroke-destructive/15",
+    text: "text-destructive",
+  },
+};
+
+const PENDING_STYLES = {
+  stroke: "stroke-muted-foreground",
+  track: "stroke-border",
+  text: "text-muted-foreground",
+};
+
+type ScoreGaugeProps = {
+  label: string;
+  /** 0–100, or null when the score is not yet available. */
+  value: number | null;
+  href?: string;
+  /** Show a trailing ellipsis on the numeric label (e.g. variant scan still running). */
+  pending?: boolean;
+  className?: string;
+};
+
+const GAUGE_SIZE = 56;
+const STROKE_WIDTH = 4;
+
+function scrollToHash(href: string, e: MouseEvent<HTMLAnchorElement>) {
+  if (
+    e.defaultPrevented ||
+    e.button !== 0 ||
+    e.metaKey ||
+    e.ctrlKey ||
+    e.shiftKey ||
+    e.altKey
+  ) {
+    return;
+  }
+  const id = href.startsWith("#") ? href.slice(1) : href;
+  const target = id ? document.getElementById(id) : null;
+  if (!target) return;
+  e.preventDefault();
+  target.scrollIntoView({ behavior: "smooth", block: "start" });
+  if (typeof window !== "undefined" && window.history?.replaceState) {
+    window.history.replaceState(null, "", `#${id}`);
+  }
+}
+
+export function ScoreGauge({
+  label,
+  value,
+  href,
+  pending = false,
+  className,
+}: ScoreGaugeProps) {
+  const radius = (GAUGE_SIZE - STROKE_WIDTH) / 2;
+  const circumference = 2 * Math.PI * radius;
+  const clamped =
+    value == null ? 0 : Math.max(0, Math.min(100, Math.round(value)));
+  const styles =
+    value == null ? PENDING_STYLES : BAND_STYLES[scoreGaugeBand(clamped)];
+  const dashOffset =
+    value == null
+      ? circumference
+      : circumference - (clamped / 100) * circumference;
+
+  const content = (
+    <>
+      <div
+        className="relative shrink-0"
+        style={{ width: GAUGE_SIZE, height: GAUGE_SIZE }}
+        aria-hidden
+      >
+        <svg
+          width={GAUGE_SIZE}
+          height={GAUGE_SIZE}
+          viewBox={`0 0 ${GAUGE_SIZE} ${GAUGE_SIZE}`}
+          className="-rotate-90"
+          fill="none"
+        >
+          <circle
+            cx={GAUGE_SIZE / 2}
+            cy={GAUGE_SIZE / 2}
+            r={radius}
+            className={cn("fill-none", styles.track)}
+            strokeWidth={STROKE_WIDTH}
+          />
+          {value != null ? (
+            <circle
+              cx={GAUGE_SIZE / 2}
+              cy={GAUGE_SIZE / 2}
+              r={radius}
+              className={cn("fill-none", styles.stroke)}
+              strokeWidth={STROKE_WIDTH}
+              strokeLinecap="round"
+              strokeDasharray={circumference}
+              strokeDashoffset={dashOffset}
+            />
+          ) : null}
+        </svg>
+        <span
+          className={cn(
+            "absolute inset-0 flex items-center justify-center text-base font-semibold tabular-nums",
+            styles.text,
+          )}
+        >
+          {value == null ? "—" : clamped}
+        </span>
+      </div>
+      <span className="mt-1 max-w-22 text-center text-xs leading-tight text-muted-foreground">
+        {label}
+        {pending ? "…" : null}
+      </span>
+    </>
+  );
+
+  const rootClass = cn(
+    "flex flex-col items-center gap-0",
+    href &&
+      "rounded-lg transition hover:bg-accent/60 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+    className,
+  );
+
+  if (href) {
+    return (
+      <a
+        href={href}
+        onClick={(e) => scrollToHash(href, e)}
+        className={rootClass}
+        aria-label={
+          value == null
+            ? `${label}: not available`
+            : `${label}: ${clamped} out of 100${pending ? ", updating" : ""}`
+        }
+      >
+        {content}
+      </a>
+    );
+  }
+
+  return (
+    <div
+      className={rootClass}
+      role="img"
+      aria-label={
+        value == null
+          ? `${label}: not available`
+          : `${label}: ${clamped} out of 100${pending ? ", updating" : ""}`
+      }
+    >
+      {content}
+    </div>
+  );
+}

package/src/components/Sidebar.tsx

@@ -1,9 +1,10 @@
-import { useEffect, useMemo, useState } from "react";
+import { useEffect, useMemo, useRef, useState } from "react";
 import { IconChevronDown, IconMoon, IconSearch, IconSun } from "./icons";
 import { ToggleGroup, ToggleGroupItem } from "./ui/toggle-group";
 
 import {
   componentCatalogTreeFromReport,
+  resolveFamilyNavigationTarget,
 } from "../dashboard/aggregate";
 import type { WorkspaceReport } from "../types/report";
 import type { HashRoute } from "../shell/hashRoute";
@@ -66,6 +67,20 @@ function sectionLabel(text: string) {
   );
 }
 
+function scrollActiveNavItemToTop(nav: HTMLElement) {
+  const active = nav.querySelector<HTMLElement>('[data-nav-active="true"]');
+  if (!active) return;
+
+  const activeRect = active.getBoundingClientRect();
+  const navRect = nav.getBoundingClientRect();
+  const visible =
+    activeRect.bottom > navRect.top && activeRect.top < navRect.bottom;
+  if (visible) return;
+
+  const offset = activeRect.top - navRect.top;
+  nav.scrollTop += offset;
+}
+
 export function Sidebar({
   report,
   reportLoading,
@@ -77,17 +92,25 @@ export function Sidebar({
   onThemeChange,
   catalogNames,
 }: Props) {
-  const catalogTree = useMemo(() => componentCatalogTreeFromReport(report), [report]);
-  const [expandedFamilies, setExpandedFamilies] = useState<Set<string>>(() => new Set());
+  const catalogTree = useMemo(
+    () => componentCatalogTreeFromReport(report),
+    [report],
+  );
+  const navRef = useRef<HTMLElement>(null);
+  const [expandedFamilies, setExpandedFamilies] = useState<Set<string>>(
+    () => new Set(),
+  );
   const tokensActive = route.view === "tokens";
   const governanceActive = route.view === "governance";
+  const catalogActive = route.view === "catalog";
 
   useEffect(() => {
     if (route.view !== "component") return;
     const activeFamily = catalogTree.find(
       (item) =>
         item.type === "family" &&
-        (item.parent === route.componentId || item.children.includes(route.componentId)),
+        (item.parent === route.componentId ||
+          item.children.includes(route.componentId)),
     );
     if (!activeFamily || activeFamily.type !== "family") return;
     setExpandedFamilies((prev) => {
@@ -98,6 +121,13 @@ export function Sidebar({
     });
   }, [catalogTree, route]);
 
+  useEffect(() => {
+    const nav = navRef.current;
+    if (!nav) return;
+    const frame = requestAnimationFrame(() => scrollActiveNavItemToTop(nav));
+    return () => cancelAnimationFrame(frame);
+  }, [route, catalogTree, expandedFamilies, catalogNames.length]);
+
   const onThemeValueChange = (value: string) => {
     // Radix ToggleGroup (single) emits "" when re-clicking the active item — keep selection.
     if (value !== "light" && value !== "dark") return;
@@ -105,11 +135,16 @@ export function Sidebar({
   };
 
   return (
-    <aside className="fixed flex h-full w-[240px] shrink-0 flex-col overflow-hidden border-r border-sidebar-border bg-sidebar text-sidebar-foreground">
-      <div className="sticky top-0 z-10 shrink-0 border-b border-sidebar-border bg-sidebar px-6 py-4">
+    <aside className="fixed flex h-full w-[240px] shrink-0 flex-col overflow-hidden border-r border-border bg-background text-sidebar-foreground">
+      <div className="sticky top-0 z-10 shrink-0 border-b border-border bg-background px-6 py-4">
         <div className="flex items-center justify-between gap-2">
-          <div className="flex items-center text-sidebar-foreground">
-            <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24">
+          <div className="flex items-center text-foreground">
+            <svg
+              xmlns="http://www.w3.org/2000/svg"
+              width="24"
+              height="24"
+              viewBox="0 0 24 24"
+            >
               <g fill="currentColor">
                 <path
                   d="m22.346,4.836l-3.182-3.182c-.779-.78-2.049-.78-2.828,0l-3.182,3.182c-.78.78-.78,2.048,0,2.828l3.182,3.182c.39.39.902.585,1.414.585s1.024-.195,1.414-.585l3.182-3.182c.78-.78.78-2.048,0-2.828Z"
@@ -152,7 +187,7 @@ export function Sidebar({
           <button
             type="button"
             onClick={onOpenCommandPalette}
-            className="flex shrink-0 items-center gap-1.5 rounded-md px-1.5 py-1 text-sidebar-foreground/70 transition hover:bg-sidebar-accent hover:text-sidebar-accent-foreground"
+            className="flex shrink-0 items-center gap-1.5 rounded-md px-1.5 py-1 text-foreground/70 transition hover:bg-accent hover:text-accent-foreground"
             aria-label="Search components and views"
           >
             <IconSearch className="size-4 shrink-0" aria-hidden />
@@ -161,29 +196,43 @@ export function Sidebar({
         </div>
       </div>
 
-      <nav className="min-h-0 flex-1 overflow-y-auto px-3 py-3">
+      <nav ref={navRef} className="min-h-0 flex-1 overflow-y-auto px-3 py-3">
         {sectionLabel("Explore")}
         <button
           type="button"
           onClick={() => onNavigate({ view: "governance" })}
           className={navButtonClass(governanceActive)}
+          data-nav-active={governanceActive ? "true" : undefined}
         >
           Governance
         </button>
+        <button
+          type="button"
+          onClick={() => onNavigate({ view: "catalog" })}
+          className={navButtonClass(catalogActive)}
+          data-nav-active={catalogActive ? "true" : undefined}
+        >
+          All components
+        </button>
         <button
           type="button"
           onClick={() => onNavigate({ view: "tokens" })}
           className={navButtonClass(tokensActive)}
+          data-nav-active={tokensActive ? "true" : undefined}
         >
           Design tokens
         </button>
 
         {sectionLabel(
-          catalogNames.length > 0 ? `Components (${catalogNames.length})` : "Components",
+          catalogNames.length > 0
+            ? `Components (${catalogNames.length})`
+            : "Components",
         )}
         <div className="space-y-0.5">
           {reportLoading && catalogNames.length === 0 ? (
-            <p className="px-2.5 py-1.5 text-sm text-sidebar-foreground/50">Loading components…</p>
+            <p className="px-2.5 py-1.5 text-sm text-sidebar-foreground/50">
+              Loading components…
+            </p>
           ) : null}
           {reportError && catalogNames.length === 0 ? (
             <p className="px-2.5 py-1.5 text-sm text-sidebar-foreground/50">
@@ -197,35 +246,47 @@ export function Sidebar({
           ) : null}
           {catalogTree.map((item) => {
             if (item.type === "component") {
-              const active = route.view === "component" && route.componentId === item.name;
+              const active =
+                route.view === "component" && route.componentId === item.name;
               return (
                 <button
                   key={item.name}
                   type="button"
-                  onClick={() => onNavigate({ view: "component", componentId: item.name })}
+                  onClick={() =>
+                    onNavigate({ view: "component", componentId: item.name })
+                  }
                   className={navButtonClass(active)}
+                  data-nav-active={active ? "true" : undefined}
                 >
                   {item.name}
                 </button>
               );
             }
 
-            const parentActive = route.view === "component" && route.componentId === item.parent;
+            const parentActive =
+              route.view === "component" && route.componentId === item.parent;
             const childActive =
-              route.view === "component" && item.children.includes(route.componentId);
+              route.view === "component" &&
+              item.children.includes(route.componentId);
+            const familyActive = parentActive || childActive;
+            const parentNavActive = parentActive && !childActive;
             const expanded = expandedFamilies.has(item.parent);
             return (
-              <div key={item.parent}>
+              <div key={item.path}>
                 <div className="flex min-w-0">
                   <button
                     type="button"
                     onClick={() =>
                       onNavigate({
                         view: "component",
-                        componentId: item.parent,
+                        componentId: resolveFamilyNavigationTarget(
+                          item,
+                          catalogNames,
+                        ),
                       })
                     }
-                    className={familyParentButtonClass(parentActive)}
+                    className={familyParentButtonClass(familyActive)}
+                    data-nav-active={parentNavActive ? "true" : undefined}
                   >
                     {item.parent}
                   </button>
@@ -242,7 +303,7 @@ export function Sidebar({
                         return next;
                       })
                     }
-                    className={familyToggleClass(parentActive || childActive)}
+                    className={familyToggleClass(familyActive)}
                     aria-label={
                       expanded
                         ? `Collapse ${item.parent} subcomponents`
@@ -259,7 +320,9 @@ export function Sidebar({
                 {expanded ? (
                   <div className="mt-0.5 space-y-0.5 border-l border-sidebar-border/70 pl-3">
                     {item.children.map((child) => {
-                      const active = route.view === "component" && route.componentId === child;
+                      const active =
+                        route.view === "component" &&
+                        route.componentId === child;
                       return (
                         <button
                           key={child}
@@ -271,6 +334,7 @@ export function Sidebar({
                             })
                           }
                           className={`${navButtonClass(active)} text-xs`}
+                          data-nav-active={active ? "true" : undefined}
                         >
                           {child}
                         </button>
@@ -298,10 +362,20 @@ export function Sidebar({
           onValueChange={onThemeValueChange}
           aria-label="Color theme"
         >
-          <ToggleGroupItem value="light" className="flex-1" aria-label="Light theme" title="Light">
+          <ToggleGroupItem
+            value="light"
+            className="flex-1"
+            aria-label="Light theme"
+            title="Light"
+          >
             <IconSun className="size-4" aria-hidden />
           </ToggleGroupItem>
-          <ToggleGroupItem value="dark" className="flex-1" aria-label="Dark theme" title="Dark">
+          <ToggleGroupItem
+            value="dark"
+            className="flex-1"
+            aria-label="Dark theme"
+            title="Dark"
+          >
             <IconMoon className="size-4" aria-hidden />
           </ToggleGroupItem>
         </ToggleGroup>

package/src/components/TokensPane.tsx

@@ -36,19 +36,17 @@ export function TokensPane({
         </p>
       </header>
       <div className="min-w-0 w-full px-8 py-8">
-        <div className="rounded-ds-lg border border-border bg-card p-6 text-card-foreground shadow-xs">
-          {hasScanned && merged ? (
-            <ScannedTokenWall view={merged} />
-          ) : hasManual ? (
-            <TokenWall catalog={tokenCatalog} />
-          ) : (
-            <p className="text-sm text-muted-foreground">
-              Run <span className="font-mono">dslinter --json</span> on a
-              project with CSS token sources, or pass a{" "}
-              <span className="font-mono">tokenCatalog</span> prop.
-            </p>
-          )}
-        </div>
+        {hasScanned && merged ? (
+          <ScannedTokenWall view={merged} />
+        ) : hasManual ? (
+          <TokenWall catalog={tokenCatalog} />
+        ) : (
+          <p className="text-sm text-muted-foreground">
+            Run <span className="font-mono">dslinter --json</span> on a project
+            with CSS token sources, or pass a{" "}
+            <span className="font-mono">tokenCatalog</span> prop.
+          </p>
+        )}
       </div>
     </div>
   );

package/src/components/controlApiTable.test.ts

@@ -26,4 +26,19 @@ describe("controlsToApiRows", () => {
       { prop: "variant", default: "\"default\"", defaultBadge: "\"default\"" },
     ]);
   });
+
+  it("maps node controls to ReactNode in the type column", () => {
+    const controls: PlaygroundControl[] = [
+      {
+        key: "actions",
+        label: "actions",
+        type: "node",
+        default: "actions",
+      },
+    ];
+
+    expect(controlsToApiRows(controls)).toMatchObject([
+      { prop: "actions", type: "ReactNode" },
+    ]);
+  });
 });

package/src/components/controlApiTable.ts

@@ -18,6 +18,8 @@ function formatDefault(c: PlaygroundControl): string {
       return String(c.default);
     case "string":
       return c.default === "" ? "—" : JSON.stringify(c.default);
+    case "node":
+      return c.default === "" ? "—" : JSON.stringify(c.default);
     case "select":
       return c.default === "" ? "—" : c.default;
     default:
@@ -33,6 +35,8 @@ function formatType(c: PlaygroundControl): string {
       return "number";
     case "string":
       return "string";
+    case "node":
+      return "ReactNode";
     case "select":
       return "string";
     default:

package/src/components/ui/badge.tsx

@@ -5,21 +5,21 @@ import { cva, type VariantProps } from "class-variance-authority";
 import { cn } from "../../lib/utils";
 
 const badgeVariants = cva(
-  "inline-flex items-center justify-center border font-semibold focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2",
+  "inline-flex rounded-full items-center justify-center border font-semibold focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2",
   {
     variants: {
       variant: {
         default:
-          "border-transparent bg-primary text-primary-foreground shadow hover:bg-primary/80",
+          "border-transparent bg-primary text-primary-foreground hover:bg-primary/80",
         secondary:
           "border-transparent bg-secondary text-secondary-foreground hover:bg-secondary/80",
         destructive:
-          "border-transparent bg-destructive text-destructive-foreground shadow hover:bg-destructive/80",
+          "border-transparent bg-destructive text-destructive-foreground hover:bg-destructive/80",
         outline: "text-foreground",
       },
       size: {
-        default: "px-2.5 py-0.5 text-xs rounded-sm",
-        sm: "px-1.5 py-0.5 font-mono text-[10px] font-normal leading-tight rounded-sm",
+        default: "px-3 py-0.5 text-xs",
+        sm: "px-2 py-0.5 font-mono text-xs font-normal leading-tight",
       },
     },
     defaultVariants: {

package/src/dashboard/ComponentCatalog.tsx

@@ -22,6 +22,7 @@ import {
   catalogAttributeProps,
   ComponentPropUsageDetail,
   buildUnusedPropSetForComponent,
+  propFrequenciesForComponent,
 } from "./ComponentPropUsageDetail";
 import { shortPath } from "./paths";
 import type { WorkspaceReport } from "../types/report";
@@ -32,11 +33,13 @@ const catalogHoverTriggerClass =
   "cursor-default text-xs underline decoration-dotted underline-offset-2 hover:text-foreground";
 
 function CatalogPropUsageHover({
+  report,
   component,
   declared,
   unusedProps,
   usedPropCount,
 }: {
+  report: WorkspaceReport;
   component: string;
   declared: string[];
   unusedProps: Set<string>;
@@ -54,11 +57,16 @@ function CatalogPropUsageHover({
           </span>
         </button>
       </HoverCardTrigger>
-      <HoverCardContent align="start" className="w-56 p-3">
+      <HoverCardContent align="start" className="w-64 p-3">
         <ComponentPropUsageDetail
           component={component}
           declared={declared}
           unusedProps={unusedProps}
+          propFrequencies={propFrequenciesForComponent(
+            report,
+            component,
+          )}
+          variant="compact"
         />
       </HoverCardContent>
     </HoverCard>
@@ -159,6 +167,7 @@ export function ComponentCatalog({
               <TableCell>
                 {attributeProps.length > 0 ? (
                   <CatalogPropUsageHover
+                    report={report}
                     component={name}
                     declared={declared}
                     unusedProps={unusedProps}