@dazl/component-gallery 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License Copyright (c) 2026 Dazl
+
+Permission is hereby granted, free of
+charge, to any person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use, copy, modify, merge,
+publish, distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice
+(including the next paragraph) shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
+ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,81 @@
+# @dazl/component-gallery
+
+A [Dazl](https://dazl.dev) integration that lets you browse and preview your project's React components.
+
+## Installation
+
+Within your React Router project:
+
+```bash
+npm install @dazl/component-gallery
+```
+
+## Setup
+
+### 1. Add the Gallery Route
+
+Create a development-only route in your React Router project:
+
+```tsx
+// app/dev/components.tsx
+import '@dazl/component-gallery/styles.css';
+export { default } from '@dazl/component-gallery/route';
+export function clientLoader() {}
+export function HydrateFallback() {}
+```
+
+Register the route:
+
+```ts
+// app/routes.ts
+import { route, type RouteConfig } from '@react-router/dev/routes';
+
+export default [
+  // ... your other routes
+  route('dev/components', 'dev/components.tsx'),
+] satisfies RouteConfig;
+```
+
+### 2. Create Component Examples
+
+Define component examples as `.example.tsx` files that export a React component as the default export:
+
+```tsx
+// app/components/button/button.example.tsx
+import { Button } from './button';
+
+export default function ButtonExample() {
+  return <Button>Click me</Button>;
+}
+```
+
+When you open the project in Dazl, it will automatically discover these files and provide a menu that lists all examples, allowing you to preview them.
+
+## Usage
+
+### Organizing Examples with Sections
+
+Use the `Section` component to group related examples within a single file:
+
+```tsx
+// app/components/button/button.example.tsx
+import { Section } from '@dazl/component-gallery';
+import { Button } from './button';
+
+export default function ButtonExample() {
+  return (
+    <>
+      <Section title="Sizes" layout="row">
+        <Button size="sm">Small</Button>
+        <Button size="md">Medium</Button>
+        <Button size="lg">Large</Button>
+      </Section>
+
+      <Section title="States" layout="column">
+        <Button disabled>Disabled</Button>
+        <Button loading>Loading</Button>
+      </Section>
+    </>
+  );
+}
+```

package/dist/example/example.d.ts

@@ -0,0 +1,7 @@
+export interface SectionProps {
+    title?: string;
+    layout?: 'row' | 'column';
+    children: React.ReactNode;
+}
+export declare const Section: ({ title, layout, children }: SectionProps) => import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=example.d.ts.map

package/dist/example/example.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"example.d.ts","sourceRoot":"","sources":["../../src/example/example.tsx"],"names":[],"mappings":"AAEA,MAAM,WAAW,YAAY;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAC;IAC1B,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC7B;AAED,eAAO,MAAM,OAAO,GAAI,6BAAwC,YAAY,4CAS3E,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './example/example';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,13 @@
+import { jsxs as c, jsx as t } from "react/jsx-runtime";
+const i = "_section_omose_1", l = "_sectionTitle_omose_9", m = "_sectionContentColumn_omose_18", C = "_sectionContentRow_omose_24", o = {
+  section: i,
+  sectionTitle: l,
+  sectionContentColumn: m,
+  sectionContentRow: C
+}, u = ({ title: n, layout: e = "column", children: s }) => /* @__PURE__ */ c("section", { className: o.section, children: [
+  n ? /* @__PURE__ */ t("div", { className: o.sectionTitle, children: n }) : null,
+  /* @__PURE__ */ t("div", { className: e === "column" ? o.sectionContentColumn : o.sectionContentRow, children: s })
+] });
+export {
+  u as Section
+};

package/dist/route/component-gallery.d.ts

@@ -0,0 +1,2 @@
+export default function ComponentGallery(): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=component-gallery.d.ts.map

package/dist/route/component-gallery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-gallery.d.ts","sourceRoot":"","sources":["../../src/route/component-gallery.tsx"],"names":[],"mappings":"AAMA,MAAM,CAAC,OAAO,UAAU,gBAAgB,4CAWvC"}

package/dist/route/example-card.d.ts

@@ -0,0 +1,8 @@
+import type { ComponentExampleInfo } from './types';
+interface ExampleCardProps {
+    example: ComponentExampleInfo;
+}
+export declare const ExampleCard: import("react").NamedExoticComponent<ExampleCardProps>;
+export declare const scrollExampleCardIntoView: (id: string) => void;
+export {};
+//# sourceMappingURL=example-card.d.ts.map

package/dist/route/example-card.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"example-card.d.ts","sourceRoot":"","sources":["../../src/route/example-card.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAIpD,UAAU,gBAAgB;IACtB,OAAO,EAAE,oBAAoB,CAAC;CACjC;AAED,eAAO,MAAM,WAAW,wDAgBtB,CAAC;AA8CH,eAAO,MAAM,yBAAyB,GAAI,IAAI,MAAM,SAoBnD,CAAC"}

package/dist/route/index.d.ts

@@ -0,0 +1,3 @@
+export * from './component-gallery';
+export { default } from './component-gallery';
+//# sourceMappingURL=index.d.ts.map

package/dist/route/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/route/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/route/index.js

@@ -0,0 +1,115 @@
+import { jsxs as u, jsx as n } from "react/jsx-runtime";
+import { useCallback as f, memo as _, useState as h, lazy as b, Suspense as g, Component as v, useMemo as w, useEffect as p, useRef as E } from "react";
+import { z as s } from "zod";
+const S = "_root_segk4_1", k = {
+  root: S
+}, y = () => f((e) => {
+  if (!e) return;
+  const r = (t) => {
+    if (!(t.target instanceof Element)) return;
+    const a = t.target.closest("a");
+    if (!a) return;
+    const o = a.getAttribute("href");
+    o && (t.preventDefault(), C(o) && window.open(o, "_blank", "noopener,noreferrer"));
+  };
+  return e.addEventListener("click", r), () => {
+    e.removeEventListener("click", r);
+  };
+}, []), C = (e) => /^[a-z][a-z0-9+.-]*:/i.test(e), x = "_card_krcb2_1", N = "_cardHeader_krcb2_10", I = "_cardContent_krcb2_19", L = "_loadingState_krcb2_23", D = "_spinner_krcb2_30", H = "_errorState_krcb2_45", P = "_errorIcon_krcb2_56", z = "_errorMessage_krcb2_60", c = {
+  card: x,
+  cardHeader: N,
+  cardContent: I,
+  loadingState: L,
+  spinner: D,
+  errorState: H,
+  errorIcon: P,
+  errorMessage: z
+}, M = _(function({ example: r }) {
+  const [t] = h(() => b(() => import(
+    /* @vite-ignore */
+    `/${r.relativePath}`
+  ))), a = y();
+  return /* @__PURE__ */ u("div", { id: r.relativePath, className: c.card, children: [
+    /* @__PURE__ */ n("h3", { className: c.cardHeader, children: r.displayName }),
+    /* @__PURE__ */ n("div", { ref: a, className: c.cardContent, children: /* @__PURE__ */ n(R, { fallback: (o) => /* @__PURE__ */ n(F, { error: o }), children: /* @__PURE__ */ n(g, { fallback: /* @__PURE__ */ n(A, {}), children: /* @__PURE__ */ n(t, {}) }) }) })
+  ] });
+}), A = () => /* @__PURE__ */ n("div", { className: c.loadingState, children: /* @__PURE__ */ n("div", { className: c.spinner }) }), F = ({ error: e }) => /* @__PURE__ */ u("div", { className: c.errorState, children: [
+  /* @__PURE__ */ n("span", { className: c.errorIcon, children: "⚠" }),
+  /* @__PURE__ */ n("span", { className: c.errorMessage, children: e.message })
+] });
+class R extends v {
+  constructor(r) {
+    super(r), this.state = { error: null };
+  }
+  static getDerivedStateFromError(r) {
+    return { error: r };
+  }
+  render() {
+    return this.state.error ? this.props.fallback(this.state.error) : this.props.children;
+  }
+}
+const j = (e) => {
+  const r = document.getElementById(e);
+  r && (r.scrollIntoView({
+    behavior: "instant",
+    block: "nearest"
+  }), r.animate(
+    [
+      { boxShadow: "0 0 0 0 #3E63DD" },
+      { boxShadow: "0 0 0 4px #3E63DD", offset: 0.2 },
+      { boxShadow: "0 0 0 0 #3E63DD" }
+    ],
+    {
+      duration: 900,
+      easing: "ease-out"
+    }
+  ));
+}, O = s.object({
+  displayName: s.string(),
+  relativePath: s.string()
+}), B = s.object({
+  columns: s.number().default(2),
+  examples: s.array(O).default([]),
+  selectedExamplePath: s.string().optional(),
+  random: s.number().optional()
+}), G = () => {
+  const [e, r] = h(() => typeof window < "u" ? window.location.hash : "");
+  return p(() => {
+    const t = () => r(window.location.hash);
+    return window.addEventListener("hashchange", t), () => window.removeEventListener("hashchange", t);
+  }, []), e;
+}, U = () => {
+  const e = G();
+  return w(() => {
+    try {
+      const r = JSON.parse(decodeURIComponent(e.slice(1)));
+      return B.parse(r);
+    } catch {
+      return { columns: 1, examples: [] };
+    }
+  }, [e]);
+}, V = (e, r) => {
+  const t = E(null);
+  return p(() => {
+    const a = t.current;
+    if (!e || !a) return;
+    let o = !1, l = !1, i = 0;
+    const d = () => {
+      l || (o = !0);
+    }, m = new ResizeObserver(() => {
+      o || (l = !0, j(e), cancelAnimationFrame(i), i = requestAnimationFrame(() => {
+        l = !1;
+      }));
+    });
+    return window.addEventListener("scroll", d), m.observe(a), () => {
+      window.removeEventListener("scroll", d), m.disconnect(), cancelAnimationFrame(i);
+    };
+  }, [e, r]), t;
+};
+function T() {
+  const { columns: e, examples: r, selectedExamplePath: t, random: a } = U(), o = V(t, a);
+  return /* @__PURE__ */ n("div", { ref: o, className: k.root, style: { "--columns": e }, children: r.map((l) => /* @__PURE__ */ n(M, { example: l }, l.relativePath)) });
+}
+export {
+  T as default
+};

package/dist/route/types.d.ts

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+declare const componentExampleInfoSchema: z.ZodObject<{
+    displayName: z.ZodString;
+    relativePath: z.ZodString;
+}, z.core.$strip>;
+export declare const componentGalleryParamsSchema: z.ZodObject<{
+    columns: z.ZodDefault<z.ZodNumber>;
+    examples: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        displayName: z.ZodString;
+        relativePath: z.ZodString;
+    }, z.core.$strip>>>;
+    selectedExamplePath: z.ZodOptional<z.ZodString>;
+    random: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type ComponentExampleInfo = z.infer<typeof componentExampleInfoSchema>;
+export type ComponentGalleryParams = z.infer<typeof componentGalleryParamsSchema>;
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/route/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/route/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,QAAA,MAAM,0BAA0B;;;iBAG9B,CAAC;AAEH,eAAO,MAAM,4BAA4B;;;;;;;;iBAKvC,CAAC;AAEH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAC9E,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC"}

package/dist/route/use-component-gallery-params.d.ts

@@ -0,0 +1,3 @@
+import { type ComponentGalleryParams } from './types';
+export declare const useComponentGalleryParams: () => ComponentGalleryParams;
+//# sourceMappingURL=use-component-gallery-params.d.ts.map

package/dist/route/use-component-gallery-params.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-component-gallery-params.d.ts","sourceRoot":"","sources":["../../src/route/use-component-gallery-params.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,sBAAsB,EAAgC,MAAM,SAAS,CAAC;AAcpF,eAAO,MAAM,yBAAyB,QAAO,sBAW5C,CAAC"}

package/dist/route/use-link-behavior-override.d.ts

@@ -0,0 +1,7 @@
+import { type RefCallback } from 'react';
+/**
+ * Always open absolute URLs in a new tab and prevent navigation for relative
+ * URLs.
+ */
+export declare const useLinkBehaviorOverride: () => RefCallback<HTMLElement>;
+//# sourceMappingURL=use-link-behavior-override.d.ts.map

package/dist/route/use-link-behavior-override.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-link-behavior-override.d.ts","sourceRoot":"","sources":["../../src/route/use-link-behavior-override.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,WAAW,EAAe,MAAM,OAAO,CAAC;AAEtD;;;GAGG;AACH,eAAO,MAAM,uBAAuB,QAAO,WAAW,CAAC,WAAW,CA0BjE,CAAC"}

package/dist/route/use-scroll-to-example-card.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Scrolls to an example card whenever the container resizes (e.g., as lazy
+ * components load). Auto-scroll stops once the user scrolls manually, and
+ * resets on dependency changes.
+ */
+export declare const useScrollToExampleCard: (relativePath: string | undefined, counter: number | undefined) => import("react").RefObject<HTMLDivElement | null>;
+//# sourceMappingURL=use-scroll-to-example-card.d.ts.map

package/dist/route/use-scroll-to-example-card.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-scroll-to-example-card.d.ts","sourceRoot":"","sources":["../../src/route/use-scroll-to-example-card.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,GAAI,cAAc,MAAM,GAAG,SAAS,EAAE,SAAS,MAAM,GAAG,SAAS,qDAqCnG,CAAC"}

package/dist/styles.css

@@ -0,0 +1 @@
+._section_omose_1{margin-bottom:32px}._section_omose_1:last-child{margin-bottom:0}._sectionTitle_omose_9{margin-bottom:16px;font-weight:700;font-size:12px;color:light-dark(#666,#999);text-transform:uppercase;letter-spacing:.05em}._sectionContentColumn_omose_18{display:flex;flex-direction:column;gap:16px}._sectionContentRow_omose_24{display:flex;flex-direction:row;flex-wrap:wrap;align-items:center;gap:16px}._root_segk4_1{display:grid;gap:16px;padding:16px;grid-template-columns:repeat(var(--columns, 1),minmax(0,1fr))}._root_segk4_1>*{scroll-margin:16px}._card_krcb2_1{border-radius:8px;padding:16px;display:flex;flex-direction:column;background-color:light-dark(#fff,#222);overflow:auto}._cardHeader_krcb2_10{margin-bottom:16px;font-weight:700;font-size:12px;color:light-dark(#666,#999);text-transform:uppercase;letter-spacing:.05em}._cardContent_krcb2_19{flex:1}._loadingState_krcb2_23{display:flex;align-items:center;justify-content:center;padding:0 32px 32px}._spinner_krcb2_30{width:24px;height:24px;border:2px solid light-dark(#eee,#444);border-top-color:light-dark(#999,#888);border-radius:50%;animation:_spin_krcb2_30 1s linear infinite}@keyframes _spin_krcb2_30{to{transform:rotate(360deg)}}._errorState_krcb2_45{padding:32px;display:flex;flex-direction:column;align-items:center;justify-content:center;gap:8px;text-align:center;color:light-dark(#ce2c31,#ec5d5e)}._errorIcon_krcb2_56{font-size:32px}._errorMessage_krcb2_60{border-radius:4px;overflow-wrap:break-word;font-weight:400;font-size:14px}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@dazl/component-gallery",
+  "version": "1.0.0",
+  "description": "View your components in a gallery inside Dazl",
+  "author": "Dazl",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./route": {
+      "import": "./dist/route/index.js",
+      "types": "./dist/route/index.d.ts"
+    },
+    "./styles.css": "./dist/styles.css",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "dist",
+    "!dist/tsconfig.tsbuildinfo"
+  ],
+  "scripts": {
+    "package": "vite build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dazl-dev/dazl-libs.git",
+    "directory": "packages/component-gallery"
+  },
+  "dependencies": {
+    "zod": ">=4.0.0"
+  },
+  "peerDependencies": {
+    "react": ">=19.0.0"
+  }
+}

package/src/example/example.module.css

@@ -0,0 +1,30 @@
+.section {
+  margin-bottom: 32px;
+}
+
+.section:last-child {
+  margin-bottom: 0;
+}
+
+.sectionTitle {
+  margin-bottom: 16px;
+  font-weight: bold;
+  font-size: 12px;
+  color: light-dark(#666, #999);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+
+.sectionContentColumn {
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+}
+
+.sectionContentRow {
+  display: flex;
+  flex-direction: row;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 16px;
+}

package/src/example/example.tsx

@@ -0,0 +1,18 @@
+import styles from './example.module.css';
+
+export interface SectionProps {
+    title?: string;
+    layout?: 'row' | 'column';
+    children: React.ReactNode;
+}
+
+export const Section = ({ title, layout = 'column', children }: SectionProps) => {
+    return (
+        <section className={styles.section}>
+            {title ? <div className={styles.sectionTitle}>{title}</div> : null}
+            <div className={layout === 'column' ? styles.sectionContentColumn : styles.sectionContentRow}>
+                {children}
+            </div>
+        </section>
+    );
+};

package/src/index.ts

@@ -0,0 +1 @@
+export * from './example/example';

package/src/route/component-gallery.module.css

@@ -0,0 +1,10 @@
+.root {
+  display: grid;
+  gap: 16px;
+  padding: 16px;
+  grid-template-columns: repeat(var(--columns, 1), minmax(0, 1fr));
+}
+
+.root > * {
+  scroll-margin: 16px;
+}

package/src/route/component-gallery.tsx

@@ -0,0 +1,18 @@
+import type { CSSProperties } from 'react';
+import styles from './component-gallery.module.css';
+import { ExampleCard } from './example-card';
+import { useComponentGalleryParams } from './use-component-gallery-params';
+import { useScrollToExampleCard } from './use-scroll-to-example-card';
+
+export default function ComponentGallery() {
+    const { columns, examples, selectedExamplePath, random } = useComponentGalleryParams();
+    const ref = useScrollToExampleCard(selectedExamplePath, random);
+
+    return (
+        <div ref={ref} className={styles.root} style={{ '--columns': columns } as CSSProperties}>
+            {examples.map((example) => (
+                <ExampleCard key={example.relativePath} example={example} />
+            ))}
+        </div>
+    );
+}

package/src/route/example-card.module.css

@@ -0,0 +1,65 @@
+.card {
+  border-radius: 8px;
+  padding: 16px;
+  display: flex;
+  flex-direction: column;
+  background-color: light-dark(#fff, #222);
+  overflow: auto;
+}
+
+.cardHeader {
+  margin-bottom: 16px;
+  font-weight: bold;
+  font-size: 12px;
+  color: light-dark(#666, #999);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+
+.cardContent {
+  flex: 1;
+}
+
+.loadingState {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 0 32px 32px 32px;
+}
+
+.spinner {
+  width: 24px;
+  height: 24px;
+  border: 2px solid light-dark(#eee, #444);
+  border-top-color: light-dark(#999, #888);
+  border-radius: 50%;
+  animation: spin 1s linear infinite;
+}
+
+@keyframes spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+.errorState {
+  padding: 32px;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 8px;
+  text-align: center;
+  color: light-dark(#ce2c31, #ec5d5e);
+}
+
+.errorIcon {
+  font-size: 32px;
+}
+
+.errorMessage {
+  border-radius: 4px;
+  overflow-wrap: break-word;
+  font-weight: 400;
+  font-size: 14px;
+}

package/src/route/example-card.tsx

@@ -0,0 +1,92 @@
+import { lazy, Component, Suspense, useState, memo } from 'react';
+import type { ComponentExampleInfo } from './types';
+import { useLinkBehaviorOverride } from './use-link-behavior-override';
+import styles from './example-card.module.css';
+
+interface ExampleCardProps {
+    example: ComponentExampleInfo;
+}
+
+export const ExampleCard = memo(function ExampleCard({ example }: ExampleCardProps) {
+    const [Component] = useState(() => lazy(() => import(/* @vite-ignore */ `/${example.relativePath}`)));
+    const contentRef = useLinkBehaviorOverride();
+
+    return (
+        <div id={example.relativePath} className={styles.card}>
+            <h3 className={styles.cardHeader}>{example.displayName}</h3>
+            <div ref={contentRef} className={styles.cardContent}>
+                <ErrorBoundary fallback={(error) => <ErrorState error={error} />}>
+                    <Suspense fallback={<LoadingState />}>
+                        <Component />
+                    </Suspense>
+                </ErrorBoundary>
+            </div>
+        </div>
+    );
+});
+
+const LoadingState = () => {
+    return (
+        <div className={styles.loadingState}>
+            <div className={styles.spinner} />
+        </div>
+    );
+};
+
+const ErrorState = ({ error }: { error: Error }) => {
+    return (
+        <div className={styles.errorState}>
+            <span className={styles.errorIcon}>⚠</span>
+            <span className={styles.errorMessage}>{error.message}</span>
+        </div>
+    );
+};
+
+interface ErrorBoundaryProps {
+    children: React.ReactNode;
+    fallback: (error: Error) => React.ReactNode;
+}
+
+interface ErrorBoundaryState {
+    error: Error | null;
+}
+
+class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+    constructor(props: ErrorBoundaryProps) {
+        super(props);
+        this.state = { error: null };
+    }
+
+    static getDerivedStateFromError(error: Error): ErrorBoundaryState {
+        return { error };
+    }
+
+    render() {
+        if (this.state.error) {
+            return this.props.fallback(this.state.error);
+        }
+        return this.props.children;
+    }
+}
+
+export const scrollExampleCardIntoView = (id: string) => {
+    const element = document.getElementById(id);
+    if (!element) return;
+
+    element.scrollIntoView({
+        behavior: 'instant',
+        block: 'nearest',
+    });
+
+    element.animate(
+        [
+            { boxShadow: '0 0 0 0 #3E63DD' },
+            { boxShadow: '0 0 0 4px #3E63DD', offset: 0.2 },
+            { boxShadow: '0 0 0 0 #3E63DD' },
+        ],
+        {
+            duration: 900,
+            easing: 'ease-out',
+        },
+    );
+};

package/src/route/index.ts

@@ -0,0 +1,2 @@
+export * from './component-gallery';
+export { default } from './component-gallery';

package/src/route/types.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+
+const componentExampleInfoSchema = z.object({
+    displayName: z.string(),
+    relativePath: z.string(),
+});
+
+export const componentGalleryParamsSchema = z.object({
+    columns: z.number().default(2),
+    examples: z.array(componentExampleInfoSchema).default([]),
+    selectedExamplePath: z.string().optional(),
+    random: z.number().optional(),
+});
+
+export type ComponentExampleInfo = z.infer<typeof componentExampleInfoSchema>;
+export type ComponentGalleryParams = z.infer<typeof componentGalleryParamsSchema>;

package/src/route/use-component-gallery-params.ts

@@ -0,0 +1,27 @@
+import { useEffect, useMemo, useState } from 'react';
+import { type ComponentGalleryParams, componentGalleryParamsSchema } from './types';
+
+const useLocationHash = (): string => {
+    const [hash, setHash] = useState(() => (typeof window !== 'undefined' ? window.location.hash : ''));
+
+    useEffect(() => {
+        const handleHashChange = () => setHash(window.location.hash);
+        window.addEventListener('hashchange', handleHashChange);
+        return () => window.removeEventListener('hashchange', handleHashChange);
+    }, []);
+
+    return hash;
+};
+
+export const useComponentGalleryParams = (): ComponentGalleryParams => {
+    const hash = useLocationHash();
+
+    return useMemo(() => {
+        try {
+            const parsed: unknown = JSON.parse(decodeURIComponent(hash.slice(1)));
+            return componentGalleryParamsSchema.parse(parsed);
+        } catch {
+            return { columns: 1, examples: [] };
+        }
+    }, [hash]);
+};

package/src/route/use-link-behavior-override.ts

@@ -0,0 +1,35 @@
+import { type RefCallback, useCallback } from 'react';
+
+/**
+ * Always open absolute URLs in a new tab and prevent navigation for relative
+ * URLs.
+ */
+export const useLinkBehaviorOverride = (): RefCallback<HTMLElement> => {
+    return useCallback((container: HTMLElement | null) => {
+        if (!container) return;
+
+        const handleClick = (event: MouseEvent) => {
+            if (!(event.target instanceof Element)) return;
+
+            const link = event.target.closest('a');
+            if (!link) return;
+
+            const href = link.getAttribute('href');
+            if (!href) return;
+
+            event.preventDefault();
+
+            if (isAbsoluteUrl(href)) {
+                window.open(href, '_blank', 'noopener,noreferrer');
+            }
+        };
+
+        container.addEventListener('click', handleClick);
+
+        return () => {
+            container.removeEventListener('click', handleClick);
+        };
+    }, []);
+};
+
+const isAbsoluteUrl = (url: string): boolean => /^[a-z][a-z0-9+.-]*:/i.test(url);

package/src/route/use-scroll-to-example-card.ts

@@ -0,0 +1,46 @@
+import { useEffect, useRef } from 'react';
+import { scrollExampleCardIntoView } from './example-card';
+
+/**
+ * Scrolls to an example card whenever the container resizes (e.g., as lazy
+ * components load). Auto-scroll stops once the user scrolls manually, and
+ * resets on dependency changes.
+ */
+export const useScrollToExampleCard = (relativePath: string | undefined, counter: number | undefined) => {
+    const containerRef = useRef<HTMLDivElement>(null);
+
+    useEffect(() => {
+        const container = containerRef.current;
+        if (!relativePath || !container) return;
+
+        let scrolledManually = false;
+        let scrollingProgrammatically = false;
+        let animationFrameId = 0;
+
+        const handleScroll = () => {
+            if (scrollingProgrammatically) return;
+            scrolledManually = true;
+        };
+
+        const resizeObserver = new ResizeObserver(() => {
+            if (scrolledManually) return;
+            scrollingProgrammatically = true;
+            scrollExampleCardIntoView(relativePath);
+            cancelAnimationFrame(animationFrameId);
+            animationFrameId = requestAnimationFrame(() => {
+                scrollingProgrammatically = false;
+            });
+        });
+
+        window.addEventListener('scroll', handleScroll);
+        resizeObserver.observe(container);
+
+        return () => {
+            window.removeEventListener('scroll', handleScroll);
+            resizeObserver.disconnect();
+            cancelAnimationFrame(animationFrameId);
+        };
+    }, [relativePath, counter]);
+
+    return containerRef;
+};