[WIP] feat: component explorer

packages/docs/angular-docs/package.json

@@ -23,7 +23,7 @@
     "watch:angular": "run-p dev:angular dev:demo-chunks",
     "watch:app": "run-p dev:app typecheck",
     "copy-build": "tsx scripts/copy-angular-demo-chunks.ts",
-    "typecheck": "react-router typegen && tsc -w --preserveWatchOutput -b tsconfig.lib.json",
+    "typecheck": "react-router typegen && tsc -b tsconfig.lib.json -w --preserveWatchOutput",
     "lint": "eslint --quiet",
     "start": "cross-env NODE_ENV=production react-router-serve ./build/server/index.js",
     "generate-page-map": "qui-mdx-vite generate-page-map -o ./scripts/temp/site-data.json",

packages/docs/angular-docs/src/components/demo/component-explorer.tsx

@@ -0,0 +1,27 @@
+import {useQdsThemeContext} from "@qualcomm-ui/react/qds-theme"
+import {
+  ComponentExplorerBase,
+  type ComponentExplorerBaseProps,
+} from "@qualcomm-ui/react-mdx/component-explorer"
+import {Theme, useTheme} from "@qualcomm-ui/react-router-utils/client"
+
+import {QdsDemo} from "./qds-demo"
+
+interface ComponentExplorerProps
+  extends Omit<ComponentExplorerBaseProps, "children"> {
+  name: string
+}
+
+export function ComponentExplorer({name, ...props}: ComponentExplorerProps) {
+  const {brand} = useQdsThemeContext()
+  const [theme] = useTheme()
+  const scheme = theme === Theme.LIGHT ? "light" : "dark"
+
+  return (
+    <ComponentExplorerBase {...props}>
+      <div data-brand={brand || "qualcomm"} data-theme={scheme}>
+        <QdsDemo hideDemoControls name={name} />
+      </div>
+    </ComponentExplorerBase>
+  )
+}

packages/docs/angular-docs/src/components/demo/index.ts

@@ -1 +1,2 @@
+export * from "./component-explorer"
 export * from "./qds-demo"

packages/docs/angular-docs/src/components/demo/qds-demo.tsx

@@ -27,6 +27,7 @@ export interface QdsDemoProps
   extends Pick<QdsAngularDemoRunnerProps, "expanded" | "wrapperProps"> {
   className?: string
   hideDemoBrandSwitcher?: boolean
+  hideDemoControls?: boolean
   name: string
 }
 
@@ -72,6 +73,7 @@ export function QdsDemo({name, ...props}: QdsDemoProps) {
 
 interface QdsDemoImplProps extends QdsDemoProps {
   demoInfo: AngularDemoInfo | null
+  hideDemoControls?: boolean
   uniqueId: string
   updating?: boolean
 }
@@ -80,6 +82,7 @@ function QdsDemoImpl({
   className,
   demoInfo,
   hideDemoBrandSwitcher: hideDemoBrandSwitcherProp,
+  hideDemoControls,
   name,
   uniqueId,
   updating,
@@ -128,7 +131,7 @@ function QdsDemoImpl({
   }, [])
 
   useEffect(() => {
-    if (!mountedRef.current) {
+    if (!mountedRef.current || hideDemoControls) {
       return
     }
     const demo = demoRef.current!
@@ -165,7 +168,7 @@ function QdsDemoImpl({
     return () => {
       observer.disconnect()
     }
-  }, [demoInfo?.dimensions?.height, name])
+  }, [demoInfo?.dimensions?.height, name, hideDemoControls])
 
   useEffect(() => {
     let mounted = true
@@ -185,8 +188,32 @@ function QdsDemoImpl({
     }
   }, [])
 
+  const demoContent = (
+    <>
+      {demoInfo?.initialHtml &&
+      !demoContentRendered &&
+      !import.meta.env?.DEV ? (
+        <div
+          className="qds-demo-runner__ssr-placeholder"
+          dangerouslySetInnerHTML={{__html: demoInfo.initialHtml}}
+        ></div>
+      ) : null}
+      {/* @ts-expect-error jsx type not accounted for */}
+      <angular-demo
+        ref={codeDemoRef}
+        componentName={demoInfo?.componentClass}
+        data-demo-rendered={booleanDataAttr(demoContentRendered)}
+        filePath={demoInfo?.filePath}
+      />
+    </>
+  )
+
+  if (hideDemoControls) {
+    return <div ref={demoRef}>{demoContent}</div>
+  }
+
   return (
-    <Fragment>
+    <>
       <QdsAngularDemoRunner
         ref={demoRef}
         className={className}
@@ -211,24 +238,8 @@ function QdsDemoImpl({
         )}
         {...props}
       >
-        <>
-          {demoInfo?.initialHtml &&
-          !demoContentRendered &&
-          !import.meta.env?.DEV ? (
-            <div
-              className="qds-demo-runner__ssr-placeholder"
-              dangerouslySetInnerHTML={{__html: demoInfo.initialHtml}}
-            ></div>
-          ) : null}
-          {/* @ts-expect-error jsx type not accounted for */}
-          <angular-demo
-            ref={codeDemoRef}
-            componentName={demoInfo?.componentClass}
-            data-demo-rendered={booleanDataAttr(demoContentRendered)}
-            filePath={demoInfo?.filePath}
-          />
-        </>
+        {demoContent}
       </QdsAngularDemoRunner>
-    </Fragment>
+    </>
   )
 }

packages/docs/angular-docs/src/routes/components+/slider+/_slider.mdx

@@ -7,7 +7,7 @@ import {
   TypeDocAngularAttributes,
   TypeDocProps,
 } from "@qualcomm-ui/react-mdx/typedoc"
-import {QdsDemo} from "~components/demo"
+import {ComponentExplorer, QdsDemo} from "~components/demo"
 
 # {frontmatter.title}
 
@@ -276,6 +276,26 @@ import {SliderModule} from "@qualcomm-ui/angular/slider"
 export class SliderWithCustomMarkers {}
 ```
 
+## Explorer
+
+<ComponentExplorer
+  linkPrefix="q-slider"
+  name="SliderExplorerDemo"
+  parts={[
+    "root",
+    "label",
+    "value-text",
+    "control",
+    "track",
+    {name: "range", link: "#q-slider-range"}, // link override example
+    "thumb",
+    "marker-group",
+    "marker",
+    "hint",
+    "error-text",
+  ]}
+/>
+
 ## API
 
 ### q-slider
@@ -290,37 +310,37 @@ The `q-slider` component extends the [q-slider-root](./#q-slider-root) directive
 
 <TypeDocProps name="SliderRootDirective" />
 
-<TypeDocAngularAttributes name={["QdsSliderProps", "SliderRootBindings"]} />
+<TypeDocAngularAttributes name="SliderRootBindings" />
 
 ### q-slider-label
 
 <TypeDocProps name="SliderLabelDirective" />
 
-<TypeDocAngularAttributes name={"SliderLabelBindings"} />
+<TypeDocAngularAttributes name="SliderLabelBindings" />
 
 ### q-slider-value-text
 
 <TypeDocProps name="SliderValueTextDirective" />
 
-<TypeDocAngularAttributes name={"SliderValueTextBindings"} />
+<TypeDocAngularAttributes name="SliderValueTextBindings" />
 
 ### q-slider-control
 
 <TypeDocProps name="SliderControlDirective" />
 
-<TypeDocAngularAttributes name={"SliderControlBindings"} />
+<TypeDocAngularAttributes name="SliderControlBindings" />
 
 ### q-slider-track
 
 <TypeDocProps name="SliderTrackDirective" />
 
-<TypeDocAngularAttributes name={"SliderTrackBindings"} />
+<TypeDocAngularAttributes name="SliderTrackBindings" />
 
 ### q-slider-range
 
 <TypeDocProps name="SliderRangeDirective" />
 
-<TypeDocAngularAttributes name={"SliderRangeBindings"} />
+<TypeDocAngularAttributes name="SliderRangeBindings" />
 
 ### q-slider-thumbs shortcut
 
@@ -330,19 +350,19 @@ The `q-slider` component extends the [q-slider-root](./#q-slider-root) directive
 
 <TypeDocProps name="SliderThumbDirective" />
 
-<TypeDocAngularAttributes name={"SliderThumbBindings"} />
+<TypeDocAngularAttributes name="SliderThumbBindings" />
 
 ### q-slider-thumb-indicator
 
 <TypeDocProps name="SliderThumbIndicatorDirective" />
 
-<TypeDocAngularAttributes name={"SliderThumbIndicatorBindings"} />
+<TypeDocAngularAttributes name="SliderThumbIndicatorBindings" />
 
 ### q-slider-hidden-input
 
 <TypeDocProps name="SliderHiddenInputDirective" />
 
-<TypeDocAngularAttributes name={"SliderHiddenInputBindings"} />
+<TypeDocAngularAttributes name="SliderHiddenInputBindings" />
 
 ### q-slider-markers shortcut
 
@@ -352,22 +372,22 @@ The `q-slider` component extends the [q-slider-root](./#q-slider-root) directive
 
 <TypeDocProps name="SliderMarkerGroupDirective" />
 
-<TypeDocAngularAttributes name={"SliderMarkerGroupBindings"} />
+<TypeDocAngularAttributes name="SliderMarkerGroupBindings" />
 
 ### q-slider-marker
 
 <TypeDocProps name="SliderMarkerDirective" />
 
-<TypeDocAngularAttributes name={"SliderMarkerBindings"} />
+<TypeDocAngularAttributes name="SliderMarkerBindings" />
 
 ### q-slider-hint
 
 <TypeDocProps name="SliderHintDirective" />
 
-<TypeDocAngularAttributes name={"SliderHintBindings"} />
+<TypeDocAngularAttributes name="SliderHintBindings" />
 
 ### q-slider-error-text
 
 <TypeDocProps name="SliderErrorTextDirective" />
 
-<TypeDocAngularAttributes name={"SliderErrorTextBindings"} />
+<TypeDocAngularAttributes name="SliderErrorTextBindings" />

packages/docs/angular-docs/src/routes/components+/slider+/demos/slider-explorer-demo.ts

@@ -0,0 +1,17 @@
+import {Component} from "@angular/core"
+
+import {SliderModule} from "@qualcomm-ui/angular/slider"
+
+@Component({
+  imports: [SliderModule],
+  selector: "slider-explorer-demo",
+  template: `
+    <q-slider
+      class="sm:w-80"
+      hint="Some contextual help here"
+      label="Choose a value"
+      [defaultValue]="[25]"
+    />
+  `,
+})
+export class SliderExplorerDemo {}

packages/docs/react-docs/src/components/demo/component-explorer.tsx

@@ -0,0 +1,30 @@
+import type {ReactNode} from "react"
+
+import {useQdsThemeContext} from "@qualcomm-ui/react/qds-theme"
+import {
+  ComponentExplorerBase,
+  type ComponentExplorerBaseProps,
+} from "@qualcomm-ui/react-mdx/component-explorer"
+import {Theme, useTheme} from "@qualcomm-ui/react-router-utils/client"
+
+interface ComponentExplorerProps
+  extends Omit<ComponentExplorerBaseProps, "children"> {
+  component: () => ReactNode
+}
+
+export function ComponentExplorer({
+  component: Component,
+  ...props
+}: ComponentExplorerProps): ReactNode {
+  const [theme] = useTheme()
+  const {brand} = useQdsThemeContext()
+  const scheme = theme === Theme.LIGHT ? "light" : "dark"
+
+  return (
+    <ComponentExplorerBase {...props}>
+      <div data-brand={brand || "qualcomm"} data-theme={scheme}>
+        <Component />
+      </div>
+    </ComponentExplorerBase>
+  )
+}

packages/docs/react-docs/src/components/demo/index.ts

@@ -1 +1,2 @@
+export * from "./component-explorer"
 export * from "./demo"

packages/docs/react-docs/src/routes/components+/checkbox+/_checkbox.mdx

@@ -3,7 +3,7 @@ title: Checkbox
 group: Form Controls
 ---
 
-import {Demo} from "~components/demo"
+import {ComponentExplorer, Demo} from "~components/demo"
 import * as demos from "./demos"
 import {TypeDocAttributes, TypeDocProps} from "@qualcomm-ui/react-mdx/typedoc"
 import {Checkbox} from "@qualcomm-ui/react/checkbox"
@@ -110,6 +110,14 @@ The composite elements are only intended to be used as direct descendants of the
 </Checkbox.Root>
 ```
 
+## Explorer
+
+<ComponentExplorer
+  component={demos.CheckboxExplorerDemo}
+  linkPrefix="checkbox"
+  parts={["root", "label", "control", "indicator", "error-text"]}
+/>
+
 ## API
 
 ### \<Checkbox\>

packages/docs/react-docs/src/routes/components+/checkbox+/demos/checkbox-explorer-demo.tsx

@@ -0,0 +1,7 @@
+import type {ReactElement} from "react"
+
+import {Checkbox} from "@qualcomm-ui/react/checkbox"
+
+export function CheckboxExplorerDemo(): ReactElement {
+  return <Checkbox checked label="Example Checkbox" />
+}

packages/docs/react-docs/src/routes/components+/checkbox+/demos/index.ts

@@ -1,6 +1,7 @@
 export * from "./checkbox-composite-layout-demo"
 export * from "./checkbox-controlled-demo"
 export * from "./checkbox-disabled-demo"
+export * from "./checkbox-explorer-demo"
 export * from "./checkbox-react-hook-form-demo"
 export * from "./checkbox-simple-demo"
 export * from "./checkbox-sizes-demo"