dslinter 0.0.6

package/src/shell/PlaygroundUsageCode.tsx

@@ -0,0 +1,51 @@
+import { useEffect, useRef, useState } from "react";
+import "@shikijs/twoslash/style-rich.css";
+import { renderPlaygroundUsageHtml } from "./playgroundUsageHighlight";
+
+const shellClass =
+  "playground-usage-shiki mt-4 overflow-x-auto rounded-lg border bg-gray-900 p-4 text-sm leading-relaxed shadow-xs " +
+  "[&_.shiki]:!bg-transparent [&_pre.shiki]:!m-0 [&_pre.shiki]:!bg-transparent [&_pre.shiki]:!p-0";
+
+const plainPreClass =
+  "m-0 whitespace-pre font-mono text-sm leading-relaxed text-gray-100";
+
+type Props = {
+  source: string;
+};
+
+export function PlaygroundUsageCode({ source }: Props) {
+  const [html, setHtml] = useState<string | null>(null);
+  const seq = useRef(0);
+
+  useEffect(() => {
+    const id = ++seq.current;
+    const ac = new AbortController();
+    setHtml(null);
+
+    void (async () => {
+      try {
+        const next = await renderPlaygroundUsageHtml(source, ac.signal);
+        if (id !== seq.current) return;
+        setHtml(next);
+      } catch (e) {
+        if ((e as { name?: string }).name === "AbortError") return;
+        if (id !== seq.current) return;
+        setHtml(null);
+      }
+    })();
+
+    return () => ac.abort();
+  }, [source]);
+
+  if (html) {
+    return (
+      <div className={shellClass} dangerouslySetInnerHTML={{ __html: html }} />
+    );
+  }
+
+  return (
+    <pre className={shellClass}>
+      <code className={plainPreClass}>{source}</code>
+    </pre>
+  );
+}

package/src/shell/PlaygroundVariantMatrix.tsx

@@ -0,0 +1,68 @@
+import type { PlaygroundArgs } from "../types/controls";
+import type { PlaygroundPreviewComponent } from "../types/preview";
+import { Badge } from "@/components/ui/badge";
+import { PLAYGROUND_VARIANT_MATRIX_CAP } from "../playground/enumerateControlCombinations";
+
+type Props = {
+  Preview: PlaygroundPreviewComponent;
+  combinations: PlaygroundArgs[];
+  finiteAxisKeys: string[];
+  totalCount: number;
+  capped: boolean;
+};
+
+function formatValue(value: string | number | boolean): string {
+  if (typeof value === "string") return value;
+  return JSON.stringify(value);
+}
+
+export function PlaygroundVariantMatrix({
+  Preview,
+  combinations,
+  finiteAxisKeys,
+  totalCount,
+  capped,
+}: Props) {
+  if (combinations.length === 0) return null;
+
+  return (
+    <>
+      {capped ? (
+        <p className="rounded-md border border-border bg-muted/60 px-3 py-2 text-sm text-muted-foreground">
+          Showing {combinations.length} of {totalCount} combinations (limit{" "}
+          {PLAYGROUND_VARIANT_MATRIX_CAP}). Reduce select options or split
+          controls to preview more here.
+        </p>
+      ) : null}
+      <div className="mt-4 flex flex-col gap-4">
+        {combinations.map((combo) => (
+          <div
+            key={finiteAxisKeys
+              .map((k) => `${k}:${formatValue(combo[k] ?? "")}`)
+              .join("|")}
+            className="flex min-w-0 flex-col overflow-hidden rounded-lg border border-border bg-card text-card-foreground shadow-xs"
+          >
+            <div className="flex flex-wrap gap-1 border-b p-2">
+              {finiteAxisKeys.map((k) => {
+                const v = combo[k];
+                return (
+                  <Badge
+                    key={k}
+                    variant="outline"
+                    size="sm"
+                    className="font-mono text-xs"
+                  >
+                    {k}={v === undefined ? "?" : formatValue(v)}
+                  </Badge>
+                );
+              })}
+            </div>
+            <div className="min-w-0 bg-card p-3">
+              <Preview values={combo} />
+            </div>
+          </div>
+        ))}
+      </div>
+    </>
+  );
+}

package/src/shell/Section.tsx

@@ -0,0 +1,34 @@
+export function Section({
+  id,
+  children,
+  title,
+  description,
+  actions,
+}: {
+  id: string;
+  children: React.ReactNode;
+  title: string;
+  description: string;
+  actions?: React.ReactNode;
+}) {
+  return (
+    <section id={id} className="scroll-mt-20">
+      <div className="flex items-center justify-between gap-2">
+        <div>
+          <h2 className="text-lg/none font-semibold tracking-tight text-foreground">
+            {title}
+          </h2>
+          {description ? (
+            <p className="text-sm mt-1.5 text-muted-foreground">
+              {description}
+            </p>
+          ) : null}
+        </div>
+        {actions ? (
+          <div className="flex items-center gap-2">{actions}</div>
+        ) : null}
+      </div>
+      <div className="mt-3">{children}</div>
+    </section>
+  );
+}

package/src/shell/Sidebar.tsx

@@ -0,0 +1,203 @@
+import { useEffect, useState } from "react";
+import { IconMoon, IconSearch, IconSun } from "@/components/icons";
+import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";
+
+import type { PlaygroundEntry } from "../types/playground";
+import type { HashRoute } from "./hashRoute";
+import type { DashboardThemePreference } from "./DashboardLayout";
+
+type Props = {
+  entries: PlaygroundEntry[];
+  route: HashRoute;
+  onNavigate: (next: HashRoute) => void;
+  onOpenCommandPalette: () => void;
+  theme: DashboardThemePreference;
+  onThemeChange: (next: DashboardThemePreference) => void;
+};
+
+function SearchShortcutBadge() {
+  const [label, setLabel] = useState("⌘K");
+  useEffect(() => {
+    const mac = /Mac|iPhone|iPod|iPad/i.test(navigator.userAgent);
+    setLabel(mac ? "⌘K" : "Ctrl+K");
+  }, []);
+  return (
+    <kbd className="pointer-events-none select-none rounded border border-sidebar-border bg-sidebar-accent px-1 py-px font-mono text-[10px] font-medium leading-tight text-sidebar-foreground/80 tabular-nums">
+      {label}
+    </kbd>
+  );
+}
+
+function navButtonClass(active: boolean) {
+  return `w-full rounded-md px-2.5 py-1.5 text-left text-sm transition ${
+    active
+      ? "bg-sidebar-primary text-sidebar-primary-foreground shadow-xs"
+      : "text-sidebar-foreground/80 hover:bg-sidebar-accent hover:text-sidebar-accent-foreground"
+  }`;
+}
+
+function sectionLabel(text: string) {
+  return (
+    <p className="mb-1.5 mt-4 px-2.5 text-xs font-semibold uppercase tracking-wider text-sidebar-foreground/50 first:mt-0">
+      {text}
+    </p>
+  );
+}
+
+export function Sidebar({
+  entries,
+  route,
+  onNavigate,
+  onOpenCommandPalette,
+  theme,
+  onThemeChange,
+}: Props) {
+  const tokensActive = route.view === "tokens";
+  const governanceActive = route.view === "governance";
+
+  const onThemeValueChange = (value: string) => {
+    if (value !== "light" && value !== "dark") return;
+    onThemeChange(value);
+  };
+
+  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">
+        <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"
+            >
+              <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"
+                  fill="currentColor"
+                  strokeWidth="0"
+                ></path>
+                <rect
+                  x="2"
+                  y="2"
+                  width="9"
+                  height="9"
+                  rx="2"
+                  ry="2"
+                  strokeWidth="0"
+                  fill="currentColor"
+                ></rect>
+                <rect
+                  x="13"
+                  y="13"
+                  width="9"
+                  height="9"
+                  rx="2"
+                  ry="2"
+                  strokeWidth="0"
+                  fill="currentColor"
+                ></rect>
+                <rect
+                  x="2"
+                  y="13"
+                  width="9"
+                  height="9"
+                  rx="2"
+                  ry="2"
+                  strokeWidth="0"
+                  fill="currentColor"
+                ></rect>
+              </g>
+            </svg>
+          </div>
+          <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"
+            aria-label="Search components and views"
+          >
+            <IconSearch className="size-4 shrink-0" aria-hidden />
+            <SearchShortcutBadge />
+          </button>
+        </div>
+      </div>
+
+      <nav 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)}
+        >
+          Governance
+        </button>
+        <button
+          type="button"
+          onClick={() => onNavigate({ view: "tokens" })}
+          className={navButtonClass(tokensActive)}
+        >
+          Design tokens
+        </button>
+
+        {sectionLabel("Components")}
+        <div className="space-y-0.5">
+          {entries.map((e, i) => {
+            const active =
+              route.view === "component" && route.componentId === e.id;
+            const prev = entries[i - 1];
+            const showGroup =
+              Boolean(e.meta.group) &&
+              (!prev || prev.meta.group !== e.meta.group);
+            return (
+              <div key={e.id}>
+                {showGroup && e.meta.group ? sectionLabel(e.meta.group) : null}
+                <button
+                  type="button"
+                  onClick={() =>
+                    onNavigate({ view: "component", componentId: e.id })
+                  }
+                  className={navButtonClass(active)}
+                >
+                  {e.meta.title}
+                </button>
+              </div>
+            );
+          })}
+        </div>
+      </nav>
+
+      <div className="shrink-0 border-t border-sidebar-border px-3 py-3">
+        <p className="mb-2 px-2.5 text-xs font-semibold uppercase tracking-wider text-sidebar-foreground/50">
+          Appearance
+        </p>
+        <ToggleGroup
+          type="single"
+          variant="outline"
+          size="sm"
+          spacing={0}
+          className="w-full"
+          value={theme}
+          onValueChange={onThemeValueChange}
+          aria-label="Color theme"
+        >
+          <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"
+          >
+            <IconMoon className="size-4" aria-hidden />
+          </ToggleGroupItem>
+        </ToggleGroup>
+      </div>
+    </aside>
+  );
+}

package/src/shell/TokensPane.tsx

@@ -0,0 +1,26 @@
+import type { TokenCatalog } from "../types/tokenCatalog";
+import { TokenWall } from "../dashboard/TokenWall";
+
+export function TokensPane({ tokenCatalog }: { tokenCatalog: TokenCatalog }) {
+  return (
+    <div className="min-h-0 flex-1 overflow-auto bg-muted/40">
+      <header className="border-b border-border bg-card px-8 py-6">
+        <p className="text-xs font-semibold uppercase tracking-wide text-muted-foreground">
+          System
+        </p>
+        <h1 className="mt-1 text-lg font-semibold tracking-tight text-foreground">
+          Design tokens
+        </h1>
+        <p className="mt-2 text-sm text-muted-foreground">
+          Supply a catalog object (same shape as your Tailwind theme docs) —
+          keep it aligned with your design tokens.
+        </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">
+          <TokenWall catalog={tokenCatalog} />
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/shell/controlApiTable.ts

@@ -0,0 +1,53 @@
+import type { PlaygroundControl } from "../types/controls";
+
+export type ApiTableRow = {
+  prop: string;
+  type: string;
+  /** Select option values; Type column renders these as badges instead of a `|` string. */
+  unionLiterals: string[] | null;
+  default: string;
+};
+
+function formatDefault(c: PlaygroundControl): string {
+  switch (c.type) {
+    case "boolean":
+      return String(c.default);
+    case "number":
+      return String(c.default);
+    case "string":
+      return c.default === "" ? "—" : JSON.stringify(c.default);
+    case "select":
+      return c.default === "" ? "—" : c.default;
+    default:
+      return "—";
+  }
+}
+
+function formatType(c: PlaygroundControl): string {
+  switch (c.type) {
+    case "boolean":
+      return "boolean";
+    case "number":
+      return "number";
+    case "string":
+      return "string";
+    case "select":
+      return "string";
+    default:
+      return "—";
+  }
+}
+
+function unionLiteralsForControl(c: PlaygroundControl): string[] | null {
+  if (c.type !== "select") return null;
+  return c.options.map((o) => o.value);
+}
+
+export function controlsToApiRows(controls: PlaygroundControl[]): ApiTableRow[] {
+  return controls.map((c) => ({
+    prop: c.key,
+    type: formatType(c),
+    unionLiterals: unionLiteralsForControl(c),
+    default: formatDefault(c),
+  }));
+}

package/src/shell/hashRoute.ts

@@ -0,0 +1,49 @@
+export type HashRoute =
+  | { view: "tokens" }
+  | { view: "governance" }
+  | { view: "component"; componentId: string };
+
+const PREFIX = "#!/";
+
+function stripShebang(hash: string): string {
+  if (hash.startsWith(PREFIX)) {
+    return hash.slice(PREFIX.length);
+  }
+  if (hash.startsWith("#")) {
+    return hash.slice(1);
+  }
+  return hash;
+}
+
+export function parseHashRoute(hash: string): HashRoute {
+  const raw = stripShebang(hash).trim();
+  if (raw === "" || raw === "overview") {
+    return { view: "governance" };
+  }
+  if (raw === "tokens") {
+    return { view: "tokens" };
+  }
+  if (raw === "governance") {
+    return { view: "governance" };
+  }
+  if (raw.startsWith("component/")) {
+    const componentId = decodeURIComponent(raw.slice("component/".length));
+    if (componentId.length > 0) {
+      return { view: "component", componentId };
+    }
+  }
+  return { view: "governance" };
+}
+
+export function formatHashRoute(route: HashRoute): string {
+  switch (route.view) {
+    case "tokens":
+      return `${PREFIX}tokens`;
+    case "governance":
+      return `${PREFIX}governance`;
+    case "component":
+      return `${PREFIX}component/${encodeURIComponent(route.componentId)}`;
+    default:
+      return `${PREFIX}governance`;
+  }
+}

package/src/shell/playgroundUsageHighlight.ts

@@ -0,0 +1,53 @@
+import tsx from "@shikijs/langs/tsx";
+import githubDark from "@shikijs/themes/github-dark";
+import { createHighlighterCore, type HighlighterCore } from "shiki/core";
+import { createJavaScriptRegexEngine } from "shiki/engine/javascript";
+
+const THEME = "github-dark";
+const LANG = "tsx";
+
+/** When true, run Twoslash (CDN ATA + hover) before highlighting. */
+export function usageSnippetNeedsTwoslash(source: string): boolean {
+  return (
+    /\^\?/.test(source) ||
+    /\/\/\s*@(?:errors|error|log|warn|filename|noErrors)/m.test(source) ||
+    /\/\/\s*---cut---/.test(source)
+  );
+}
+
+let highlighterPromise: Promise<HighlighterCore> | null = null;
+
+function getHighlighter(): Promise<HighlighterCore> {
+  if (highlighterPromise == null) {
+    highlighterPromise = createHighlighterCore({
+      themes: [githubDark],
+      langs: [tsx],
+      engine: createJavaScriptRegexEngine(),
+    });
+  }
+  return highlighterPromise;
+}
+
+function assertNotAborted(signal: AbortSignal | undefined): void {
+  if (signal?.aborted) throw new DOMException("Aborted", "AbortError");
+}
+
+/**
+ * Renders usage source to Shiki HTML. Twoslash runs only when {@link usageSnippetNeedsTwoslash} is true
+ * (loaded in a separate async chunk so the default bundle stays smaller).
+ */
+export async function renderPlaygroundUsageHtml(
+  source: string,
+  signal?: AbortSignal,
+): Promise<string> {
+  const highlighter = await getHighlighter();
+  assertNotAborted(signal);
+
+  if (!usageSnippetNeedsTwoslash(source)) {
+    return highlighter.codeToHtml(source, { lang: LANG, theme: THEME });
+  }
+
+  const { renderUsageWithTwoslash } = await import("./playgroundUsageTwoslash");
+  assertNotAborted(signal);
+  return renderUsageWithTwoslash(highlighter, source, signal);
+}

package/src/shell/playgroundUsageTwoslash.ts

@@ -0,0 +1,69 @@
+import { createTransformerFactory, rendererRich } from "@shikijs/twoslash/core";
+import type { ShikiTransformer } from "@shikijs/types";
+import type { HighlighterCore } from "shiki/core";
+import { createTwoslashFromCDN, type TwoslashCdnReturn } from "twoslash-cdn";
+import type { CompilerOptions } from "typescript";
+
+const THEME = "github-dark";
+const LANG = "tsx";
+
+let twoslashPromise: Promise<TwoslashCdnReturn> | null = null;
+
+function getTwoslash(): Promise<TwoslashCdnReturn> {
+  twoslashPromise ??= (async () => {
+    const compilerOptions = {
+      lib: ["esnext", "dom"],
+      jsx: "react-jsx",
+      moduleResolution: "bundler",
+      skipLibCheck: true,
+      target: "ESNext",
+      module: "ESNext",
+      allowSyntheticDefaultImports: true,
+      esModuleInterop: true,
+    } as unknown as CompilerOptions;
+
+    const tw = createTwoslashFromCDN({
+      compilerOptions,
+    });
+    await tw.init();
+    return tw;
+  })();
+  return twoslashPromise;
+}
+
+let twoslashTransformerPromise: Promise<ShikiTransformer> | null = null;
+
+function getTwoslashTransformer(): Promise<ShikiTransformer> {
+  twoslashTransformerPromise ??= getTwoslash().then((tw) =>
+    createTransformerFactory(tw.runSync)({
+      renderer: rendererRich(),
+      throws: false,
+      langs: ["ts", "tsx"],
+    }),
+  );
+  return twoslashTransformerPromise;
+}
+
+function assertNotAborted(signal: AbortSignal | undefined): void {
+  if (signal?.aborted) throw new DOMException("Aborted", "AbortError");
+}
+
+export async function renderUsageWithTwoslash(
+  highlighter: HighlighterCore,
+  source: string,
+  signal?: AbortSignal,
+): Promise<string> {
+  const tw = await getTwoslash();
+  assertNotAborted(signal);
+  await tw.prepareTypes(source);
+  assertNotAborted(signal);
+
+  const transformer = await getTwoslashTransformer();
+  assertNotAborted(signal);
+
+  return highlighter.codeToHtml(source, {
+    lang: LANG,
+    theme: THEME,
+    transformers: [transformer],
+  });
+}

package/src/shell/useHashRoute.ts

@@ -0,0 +1,29 @@
+import { useCallback, useSyncExternalStore } from "react";
+import { formatHashRoute, parseHashRoute, type HashRoute } from "./hashRoute";
+
+function subscribe(onStoreChange: () => void) {
+  window.addEventListener("hashchange", onStoreChange);
+  return () => window.removeEventListener("hashchange", onStoreChange);
+}
+
+function getHashSnapshot() {
+  return window.location.hash || "#!/governance";
+}
+
+function getServerHashSnapshot() {
+  return "#!/governance";
+}
+
+export function useHashRoute(): [HashRoute, (next: HashRoute) => void] {
+  const hash = useSyncExternalStore(subscribe, getHashSnapshot, getServerHashSnapshot);
+  const route = parseHashRoute(hash);
+
+  const navigate = useCallback((next: HashRoute) => {
+    const nextHash = formatHashRoute(next);
+    if (nextHash !== window.location.hash) {
+      window.location.hash = nextHash;
+    }
+  }, []);
+
+  return [route, navigate];
+}