📝 Add docstrings to feat/configurator-pzds-pivot

coderabbitai[bot] · web-flow · commit 2171c3f9554e · 2025-11-03T00:59:34.000Z
Docstrings generation was requested by @shayancoin. * #621 (comment) The following files were modified: * `frontend/src/app/configurator/ClientPage.tsx` * `frontend/src/app/configurator/page.tsx` * `frontend/src/app/layout.tsx` * `frontend/src/components/OrderSummaryCard.tsx` * `frontend/src/components/PricingFooter.tsx` * `frontend/src/components/Viewer2D.tsx` * `frontend/src/otel/viewer2d-instrumentation.ts`
diff --git a/frontend/src/app/configurator/ClientPage.tsx b/frontend/src/app/configurator/ClientPage.tsx
@@ -8,6 +8,11 @@ import PricingFooter from '@/components/PricingFooter'
 import { Viewer2D } from '@/components/Viewer2D'
 import { initOtelRoute } from '@/lib/otel-route'
 
+/**
+ * Renders a full-size, centered loading spinner to use as a Suspense fallback.
+ *
+ * @returns A JSX element containing a full-height, centered Spinner.
+ */
 function ViewerFallback() {
   return (
     <div className="flex h-full w-full items-center justify-center">
@@ -16,6 +21,13 @@ function ViewerFallback() {
   )
 }
 
+/**
+ * Renders the client page layout containing a 2D viewer and a configurator panel.
+ *
+ * Initializes OTEL routing on mount and presents the viewer section (using Suspense with a spinner fallback) alongside a right-side configurator panel and pricing footer.
+ *
+ * @returns The React element for the client page layout with the viewer section and configurator aside.
+ */
 export default function ClientPage() {
   useEffect(() => {
     initOtelRoute()
@@ -44,4 +56,4 @@ export default function ClientPage() {
       </div>
     </main>
   )
-}
+}
diff --git a/frontend/src/app/configurator/page.tsx b/frontend/src/app/configurator/page.tsx
@@ -2,6 +2,11 @@ import ClientPage from './ClientPage'
 
 export const dynamic = 'force-dynamic'
 
+/**
+ * Renders the client-side configurator page.
+ *
+ * @returns The ClientPage React element
+ */
 export default function Page() {
   return <ClientPage />
-}
+}
diff --git a/frontend/src/app/layout.tsx b/frontend/src/app/layout.tsx
@@ -39,6 +39,12 @@ export const metadata: Metadata = {
   },
 }
 
+/**
+ * Root layout component that applies the configured font and background, and wraps the app content with providers and initialization effects.
+ *
+ * @param children - The page or app content to render inside the layout's app container.
+ * @returns The top-level HTML structure for the application, including <html> and <body> elements with font classes and the Providers-wrapped app container.
+ */
 export default function RootLayout({
   children,
 }: {
@@ -59,4 +65,4 @@ export default function RootLayout({
       </body>
     </html>
   )
-}
+}
diff --git a/frontend/src/components/OrderSummaryCard.tsx b/frontend/src/components/OrderSummaryCard.tsx
@@ -1,11 +1,13 @@
 import { useConfiguratorStore } from '@/store/configurator'
 
 /**
- * Renders an order summary card that shows the estimated kitchen price.
+ * Render an order summary card that displays the design summary and pricing.
  *
- * The displayed price is taken from the configurator store; if the store has no price, a placeholder "—" is shown.
+ * Shows the total price, lead time, delivery ZIP, and a brief pricing note.
  *
- * @returns A React element representing the order summary card with header, estimated price, divider, and a "Continue" button.
+ * The displayed total price comes from the configurator store: if `priceCents` is `null` or `undefined`, a placeholder `"—"` is shown; otherwise `priceCents` is formatted as a dollar amount (value divided by 100).
+ *
+ * @returns A React element representing the order summary card
  */
 export default function OrderSummaryCard() {
   const { priceCents } = useConfiguratorStore()
@@ -35,4 +37,4 @@ export default function OrderSummaryCard() {
       </p>
     </section>
   )
-}
+}
diff --git a/frontend/src/components/PricingFooter.tsx b/frontend/src/components/PricingFooter.tsx
@@ -7,6 +7,11 @@ import { useConfiguratorStore } from '@/store/configurator'
 const FINANCE_TERM_MONTHS = 72
 const APR = 3.99
 
+/**
+ * Renders the pricing footer used on the configurator page, showing "Due Today", a monthly financing estimate (or dashes if price is unavailable), and an "Order Now" action.
+ *
+ * @returns The footer JSX element containing the due-today amount, the monthly estimate (or `—` when `priceCents` is null), financing information (APR and term), and an order button.
+ */
 export default function PricingFooter() {
   const { priceCents } = useConfiguratorStore()
 
@@ -48,4 +53,4 @@ export default function PricingFooter() {
       </div>
     </footer>
   )
-}
+}
diff --git a/frontend/src/components/Viewer2D.tsx b/frontend/src/components/Viewer2D.tsx
@@ -18,6 +18,13 @@ type LayerState = {
 const layerBaseClass =
   'absolute inset-0 transition-opacity duration-300 ease-out will-change-opacity'
 
+/**
+ * Render a responsive stacked-image 2D viewer for a kitchen elevation.
+ *
+ * Derives a layer manifest from the global configurator, starts and ends a compose telemetry lifecycle for each render request, and reveals each image layer as it finishes loading. The component sizes itself to the manifest aspect ratio and exposes the composed elevation as a non-interactive image region.
+ *
+ * @returns A JSX element that renders the layered elevation composition with loading state and compose lifecycle management
+ */
 export function Viewer2D() {
   const { elevation, finish, hardware, countertop } = useConfiguratorStore(
     (state) => ({
@@ -117,4 +124,4 @@ export function Viewer2D() {
   )
 }
 
-export default Viewer2D
+export default Viewer2D
diff --git a/frontend/src/otel/viewer2d-instrumentation.ts b/frontend/src/otel/viewer2d-instrumentation.ts
@@ -14,8 +14,10 @@ type ComposeHandle = {
 }
 
 /**
- * Start a `compositor.compose` span for 2D sprite composition.
- * The caller is responsible for invoking `end()` exactly once when rendering completes.
+ * Start a tracing span named `compositor.compose` for 2D sprite composition.
+ *
+ * @param context - Composition context whose `requestId`, `optionsHash`, and `layerCount` are attached to the span as attributes
+ * @returns A handle with an `end(metadata?)` method. Calling `end` records `metadata.error` (if present) and sets the span status to error; otherwise it sets the `render.duration_ms` attribute to `metadata.durationMs` (or the measured elapsed time) and sets the span status to OK, then ends the span
  */
 export function beginViewerCompose(context: ComposeContext): ComposeHandle {
   const span = tracer.startSpan(
@@ -46,4 +48,4 @@ export function beginViewerCompose(context: ComposeContext): ComposeHandle {
       span.end()
     },
   }
-}
+}
