fix(showcase/shell-docs): drop redundant env block in next.config.ts; validate NEXT_PUBLIC_BASE_URL at build time

Author: jpr5

showcase/shell-docs/next.config.ts

@@ -1,10 +1,29 @@
 import type { NextConfig } from "next";
 
-const nextConfig: NextConfig = {
-  env: {
-    NEXT_PUBLIC_BASE_URL:
-      process.env.NEXT_PUBLIC_BASE_URL || "http://localhost:3003",
-  },
-};
+// NEXT_PUBLIC_BASE_URL is inlined automatically by Next.js at build time
+// because of the NEXT_PUBLIC_ prefix. Do NOT re-declare it in an `env` block —
+// doing so bakes the build-time value into server code and overrides runtime env.
+//
+// Fail fast during an actual `next build` if the variable is missing, so we
+// never ship broken absolute URLs. Other invocations that also load this
+// config (e.g. `next lint`, `next dev`) only warn, because failing them on a
+// missing value would be noise — consumers are expected to handle the dev
+// fallback themselves (e.g. `process.env.NEXT_PUBLIC_BASE_URL ?? "http://localhost:3003"`).
+const isNextBuild = process.argv.includes("build");
+
+if (!process.env.NEXT_PUBLIC_BASE_URL) {
+  if (isNextBuild) {
+    throw new Error(
+      "NEXT_PUBLIC_BASE_URL is required for `next build` of showcase/shell-docs. " +
+        "Set it in the environment (e.g. https://your-domain.example) before running the build.",
+    );
+  }
+  // eslint-disable-next-line no-console
+  console.warn(
+    "[shell-docs] NEXT_PUBLIC_BASE_URL is not set; consumers should fall back to a sensible dev default (e.g. http://localhost:3003).",
+  );
+}
+
+const nextConfig: NextConfig = {};
 
 export default nextConfig;

showcase/shell-docs/src/components/property-reference.tsx

@@ -27,12 +27,24 @@ export function PropertyReference({
     collapsable ? true : false,
   );
 
+  // Detect nested <PropertyReference> children so we can auto-collapse them.
+  //
+  // IMPORTANT: We use *reference equality* (`child.type === PropertyReference`)
+  // rather than a name check (`child.type.name === "PropertyReference"`).
+  // In production builds, minifiers (Terser/SWC) rename function components to
+  // short identifiers like `s` or `a`, so `.name` comparisons silently fail and
+  // the `collapsable` prop never propagates. Reference equality is minifier-safe
+  // because both sides point to the same function identity after bundling.
+  //
+  // Known limitation: React.Children.map only walks *direct* children. A
+  // <PropertyReference> wrapped inside a <div> (or any other element) will NOT
+  // be detected here. Callers should nest PropertyReferences as direct
+  // siblings, not wrapped in other elements, for auto-collapse to work.
   const enhancedChildren = React.Children.map(children, (child) => {
-    if (
-      React.isValidElement(child) &&
-      (child.type as any).name === "PropertyReference"
-    ) {
-      return React.cloneElement(child, { collapsable: true } as Props);
+    if (React.isValidElement(child) && child.type === PropertyReference) {
+      return React.cloneElement(child as React.ReactElement<Props>, {
+        collapsable: true,
+      });
     }
     return child;
   });
@@ -65,7 +77,9 @@ export function PropertyReference({
         <div className="flex-1 space-x-3">
           {collapsable ? (
             <button
+              type="button"
               onClick={() => setIsCollapsed(!isCollapsed)}
+              aria-expanded={!isCollapsed}
               className="flex gap-x-2 items-center font-mono font-semibold text-[var(--accent)]"
             >
               <span className="text-xs">