southpaw 0.2.7

package/ui/blocks/uidocs.tsx

@@ -0,0 +1,1429 @@
+import { ReactElement, type ComponentType } from "react";
+import {
+  type ComponentParams,
+  create_component,
+} from "southpaw/modules/component";
+import { UI } from "..";
+import { UI_CATEGORIES } from "../../../src/constants/ui-categories";
+import { UI_EXAMPLES } from "../../../src/constants/ui-examples";
+
+type Props = {
+  ui?: Record<string, ComponentType<any>>;
+  blocks?: Record<string, ComponentType<any>>;
+  components?: Record<string, ComponentType<any>>;
+};
+
+type UIDefinition = {
+  params: ComponentParams<any, any, any, any, any>;
+  name: string;
+  description: string;
+  examples: string[];
+  category: string;
+  library: "ui" | "blocks" | "components";
+};
+
+type State = {
+  definitions: UIDefinition[];
+  searchQuery: string;
+  loading: boolean;
+  error: string | null;
+  previewZoom: number;
+  previewGrid: boolean;
+  previewRuler: boolean;
+  previewViewport: string;
+  previewTheme: "light" | "dark";
+  knobValues: Record<string, any>;
+  activeComponentId: string | null;
+  activeStoryId: number;
+  mobileMenuOpened: boolean;
+  inspectorOpened: boolean;
+  isMobile: boolean;
+  activeTab: "controls" | "actions" | "code" | "props";
+  activeLibrary: "all" | "ui" | "blocks" | "components";
+  expandedCategories: string[];
+  actionLog: Array<{ id: string; name: string; data?: any; timestamp: number }>;
+};
+
+type Computed = {
+  filteredDefinitions: (this: any) => UIDefinition[];
+  categorizedDefinitions: (
+    this: any,
+  ) => Record<string, Record<string, UIDefinition[]>>;
+};
+
+type Methods = {
+  categorizeComponent: (this: any, name: string, library: string) => string;
+  createFailedDefinition: (
+    this: any,
+    name: string,
+    library: "ui" | "blocks" | "components",
+  ) => UIDefinition;
+  extractExamples: (this: any, name: string) => string[];
+  renderPropType: (
+    this: any,
+    propDef: {
+      type: string;
+      options?: Array<string | { value: string; label?: string }>;
+      multiline?: boolean;
+    },
+  ) => string;
+  getCommonProps: (this: any) => Array<{
+    name: string;
+    type: string;
+    description: string;
+    required: boolean;
+  }>;
+  getComponentSpecificProps: (
+    this: any,
+    def: UIDefinition,
+  ) => Array<{
+    name: string;
+    type: string;
+    description: string;
+    required: boolean;
+    options?: Array<string | { value: string; label?: string }>;
+  }>;
+  handleSearchChange: (this: any, value: string) => void;
+  toggleGrid: (this: any) => void;
+  toggleRuler: (this: any) => void;
+  setZoom: (this: any, zoom: number) => void;
+  setViewport: (this: any, width: string) => void;
+  resetPreview: (this: any) => void;
+  initializeKnobs: (this: any, componentId: string, defaults: any) => void;
+  selectStory: (this: any, index: number) => void;
+  logAction: (this: any, name: string, data?: any) => void;
+  toggleCategory: (this: any, category: string) => void;
+  updateKnob: (this: any, name: string, value: any) => void;
+  renderKnobInput: (
+    this: any,
+    name: string,
+    propDef: any,
+  ) => ReactElement | null;
+  toggleMobileMenu: (this: any) => void;
+  closeMobileMenu: (this: any) => void;
+  setActiveTab: (
+    this: any,
+    tab: "controls" | "actions" | "code" | "props",
+  ) => void;
+};
+
+const Component = create_component<Props, State, Computed, any, Methods>({
+  name: "UIDocs",
+  description:
+    "A comprehensive UI documentation catalog for Southpaw UI elements",
+  props: {
+    ui: {},
+  } as Props,
+  state: {
+    definitions: [],
+    searchQuery: "",
+    loading: true,
+    error: null,
+    previewZoom: 1,
+    previewGrid: true,
+    previewRuler: false,
+    previewViewport: "Responsive",
+    previewTheme: "light",
+    knobValues: {},
+    activeComponentId: null,
+    activeStoryId: 0,
+    mobileMenuOpened: false,
+    inspectorOpened: false,
+    isMobile: false,
+    activeTab: "controls",
+    activeLibrary: "all",
+    expandedCategories: [],
+    actionLog: [],
+  },
+  computed: {
+    filteredDefinitions() {
+      return this.state.definitions.filter((def: UIDefinition) => {
+        const matchesSearch =
+          this.state.searchQuery === "" ||
+          def.name
+            .toLowerCase()
+            .includes(this.state.searchQuery.toLowerCase()) ||
+          def.description
+            .toLowerCase()
+            .includes(this.state.searchQuery.toLowerCase());
+
+        return matchesSearch;
+      });
+    },
+    categorizedDefinitions() {
+      const grouped: Record<string, Record<string, UIDefinition[]>> = {
+        ui: {},
+        blocks: {},
+        components: {},
+      };
+
+      this.computed.filteredDefinitions.forEach((def: any) => {
+        const lib = def.library;
+        if (!grouped[lib][def.category]) {
+          grouped[lib][def.category] = [];
+        }
+        grouped[lib][def.category].push(def);
+      });
+      return grouped;
+    },
+  },
+  methods: {
+    categorizeComponent(name: string, library: string): string {
+      if (library === "blocks") return "Page Blocks";
+      if (library === "components") return "App Components";
+
+      const lowerName = name.toLowerCase();
+      if (UI_CATEGORIES.layout.includes(lowerName)) return "Layout";
+      if (UI_CATEGORIES.inputs.includes(lowerName)) return "Inputs";
+      if (UI_CATEGORIES.buttons.includes(lowerName)) return "Buttons";
+      if (UI_CATEGORIES.navigation.includes(lowerName)) return "Navigation";
+      if (UI_CATEGORIES.display.includes(lowerName)) return "Display";
+      if (UI_CATEGORIES.containers.includes(lowerName)) return "Containers";
+      if (UI_CATEGORIES.utilities.includes(lowerName)) return "Utilities";
+      if (UI_CATEGORIES.data.includes(lowerName)) return "Data";
+      return "General Primitives";
+    },
+
+    createFailedDefinition(
+      name: string,
+      library: "ui" | "blocks" | "components",
+    ): UIDefinition {
+      return {
+        params: {
+          name,
+          description: "Failed to load component",
+          propsDef: {},
+          render: () => null,
+        },
+        name,
+        description: "Failed to load component",
+        examples: [`<UI.${name} />`],
+        category: "Other",
+        library,
+      };
+    },
+
+    extractExamples(name: string): string[] {
+      return (
+        UI_EXAMPLES[name] ||
+        UI_EXAMPLES.default.map((example) => example.replace("${name}", name))
+      );
+    },
+
+    renderPropType(propDef: {
+      type: string;
+      options?: Array<string | { value: string; label?: string }>;
+      multiline?: boolean;
+    }): string {
+      switch (propDef.type) {
+        case "segmented":
+          return propDef.options
+            ? `"${propDef.options
+                .map((opt) =>
+                  typeof opt === "object" ? opt.value || opt : opt,
+                )
+                .join('" | "')}"`
+            : "string";
+        case "select":
+          return "string | number";
+        case "switch":
+          return "boolean";
+        case "number":
+        case "size":
+          return "number";
+        case "color":
+          return "string (color)";
+        case "icon":
+          return "string (icon name)";
+        case "text":
+          return propDef.multiline ? "string (multiline)" : "string";
+        default:
+          return propDef.type || "any";
+      }
+    },
+
+    getCommonProps(): Array<{
+      name: string;
+      type: string;
+      description: string;
+      required: boolean;
+    }> {
+      return [
+        {
+          name: "className",
+          type: "string",
+          description: "Additional CSS class names",
+          required: false,
+        },
+        {
+          name: "style",
+          type: "CSSProperties",
+          description: "Inline styles",
+          required: false,
+        },
+        {
+          name: "id",
+          type: "string",
+          description: "Element ID",
+          required: false,
+        },
+        {
+          name: "mount_animation",
+          type: "string | AnimationConfig",
+          description: "Mount animation configuration",
+          required: false,
+        },
+        {
+          name: "p",
+          type: "number | string",
+          description: "Padding",
+          required: false,
+        },
+        {
+          name: "m",
+          type: "number | string",
+          description: "Margin",
+          required: false,
+        },
+        {
+          name: "w",
+          type: "number | string",
+          description: "Width",
+          required: false,
+        },
+        {
+          name: "h",
+          type: "number | string",
+          description: "Height",
+          required: false,
+        },
+        {
+          name: "bg",
+          type: "string",
+          description: "Background color",
+          required: false,
+        },
+        {
+          name: "c",
+          type: "string",
+          description: "Text color",
+          required: false,
+        },
+      ];
+    },
+
+    getComponentSpecificProps(def: UIDefinition): Array<{
+      name: string;
+      type: string;
+      description: string;
+      required: boolean;
+      options?: Array<string | { value: string; label?: string }>;
+    }> {
+      const propsDef = (def.params.propsDef || {}) as Record<string, any>;
+      return Object.entries(propsDef).map(([propName, propDef]) => ({
+        name: propName,
+        type: this.methods.renderPropType(propDef),
+        description: propDef.label || "No description available",
+        required: false,
+        options:
+          propDef.type === "segmented"
+            ? propDef.options
+            : propDef.type === "select"
+              ? propDef.options
+              : undefined,
+      }));
+    },
+
+    handleSearchChange(value: string) {
+      this.state.searchQuery = value;
+    },
+    toggleGrid() {
+      this.state.previewGrid = !this.state.previewGrid;
+    },
+    toggleRuler() {
+      this.state.previewRuler = !this.state.previewRuler;
+    },
+    setZoom(zoom: number) {
+      this.state.previewZoom = zoom;
+    },
+    setViewport(width: string) {
+      this.state.previewViewport = width;
+    },
+    resetPreview() {
+      this.state.previewZoom = 1;
+    },
+    initializeKnobs(componentId: string, defaults: any) {
+      if (this.state.activeComponentId === componentId) return;
+
+      this.state.activeComponentId = componentId;
+      this.state.activeStoryId = 0;
+      this.state.actionLog = [];
+      this.state.knobValues = { ...defaults };
+    },
+    selectStory(index: number) {
+      this.state.activeStoryId = index;
+      const def = this.state.definitions.find(
+        (d: any) => d.name === this.state.activeComponentId,
+      );
+      if (!def) return;
+
+      const example = def.examples[index];
+      const props: Record<string, any> = {};
+
+      const propRegex = /(\w+)=(?:{([^}]+)}|"([^"]+)")/g;
+      let match;
+      while ((match = propRegex.exec(example)) !== null) {
+        const [, key, curlyValue, quotedValue] = match;
+        const val = curlyValue !== undefined ? curlyValue : quotedValue;
+
+        if (curlyValue !== undefined) {
+          try {
+            if (val === "true") props[key] = true;
+            else if (val === "false") props[key] = false;
+            else if (!isNaN(Number(val))) props[key] = Number(val);
+            else props[key] = JSON.parse(val.replace(/'/g, '"'));
+          } catch {
+            props[key] = val;
+          }
+        } else {
+          props[key] = val;
+        }
+      }
+
+      const childrenMatch = example.match(/>([^<]+)<\/UI\./);
+      if (childrenMatch) {
+        props["children"] = childrenMatch[1].trim();
+      }
+
+      this.state.knobValues = { ...def.params.props, ...props };
+    },
+    logAction(name: string, data?: any) {
+      const entry = {
+        id: Math.random().toString(36).substring(2, 9),
+        name,
+        data,
+        timestamp: Date.now(),
+      };
+      this.state.actionLog = [entry, ...this.state.actionLog].slice(0, 50);
+    },
+    toggleCategory(category: string) {
+      if (this.state.expandedCategories.includes(category)) {
+        this.state.expandedCategories = this.state.expandedCategories.filter(
+          (c: string) => c !== category,
+        );
+      } else {
+        this.state.expandedCategories = [
+          ...this.state.expandedCategories,
+          category,
+        ];
+      }
+    },
+    updateKnob(name: string, value: any) {
+      this.state.knobValues = {
+        ...this.state.knobValues,
+        [name]: value,
+      };
+    },
+    renderKnobInput(
+      name: string,
+      propDef: {
+        type: string;
+        options?: Array<string | { value: string; label?: string }>;
+        multiline?: boolean;
+        label?: string;
+        required?: boolean;
+        min?: number;
+        max?: number;
+        step?: number;
+      },
+    ): ReactElement | null {
+      const value = this.state.knobValues[name];
+      const label = (propDef.label || name) + (propDef.required ? " *" : "");
+      switch (propDef.type) {
+        case "text":
+          return propDef.multiline ? (
+            <UI.textarea
+              label={label}
+              value={value || ""}
+              onInput={() =>
+                this.methods.updateKnob(name, this.state.knobValues[name])
+              }
+            />
+          ) : (
+            <UI.textinput
+              label={label}
+              value={value || ""}
+              onInput={() =>
+                this.methods.updateKnob(name, this.state.knobValues[name])
+              }
+            />
+          );
+        case "number":
+        case "size":
+          return (
+            <UI.numberinput
+              label={label}
+              value={value}
+              min={propDef.min}
+              max={propDef.max}
+              step={propDef.step}
+              onChange={(val) => this.methods.updateKnob(name, Number(val))}
+            />
+          );
+        case "switch":
+        case "boolean":
+          return (
+            <UI.switch
+              label={label}
+              checked={!!value}
+              onChange={(e) =>
+                this.methods.updateKnob(name, e.currentTarget.checked)
+              }
+            />
+          );
+        case "select":
+          return (
+            <UI.select
+              label={label}
+              data={propDef.options as any}
+              value={String(value)}
+              onChange={(val) => this.methods.updateKnob(name, val)}
+            />
+          );
+        case "segmented":
+          return (
+            <UI.segmentedcontrol
+              data={propDef.options as any}
+              value={String(value)}
+              onChange={(val) => this.methods.updateKnob(name, val)}
+            />
+          );
+        case "color":
+          return (
+            <UI.colorinput
+              label={label}
+              value={value || ""}
+              onChange={(val) => this.methods.updateKnob(name, val)}
+            />
+          );
+        case "list-text":
+          const items = (value as any[] | undefined) || [];
+          return (
+            <UI.flex direction="column" gap="xs">
+              <UI.text text={label} size="sm" fw={500} />
+              {items.map((item: any, idx: number) => {
+                const itemLabel =
+                  typeof item === "object"
+                    ? item.label || item.children || item.value || ""
+                    : String(item);
+                const itemContent =
+                  typeof item === "object" ? item.content || "" : "";
+
+                return (
+                  <UI.card key={idx} withBorder p="xs">
+                    <UI.flex direction="column" gap="xs">
+                      <UI.flex justify="space-between" align="center">
+                        <UI.text
+                          text={`Item ${idx + 1}`}
+                          size="xs"
+                          c="dimmed"
+                        />
+                        <UI.actionicon
+                          color="red"
+                          variant="subtle"
+                          size="sm"
+                          onClick={() => {
+                            const newItems = items.filter((_, i) => i !== idx);
+                            this.methods.updateKnob(name, newItems);
+                          }}
+                        >
+                          <UI.icon icon="remove" />
+                        </UI.actionicon>
+                      </UI.flex>
+                      <UI.textinput
+                        label="Label"
+                        value={itemLabel}
+                        onInput={(e) => {
+                          const newValue = e.currentTarget.value;
+                          const newItems = [...items];
+                          if (typeof newItems[idx] === "object") {
+                            newItems[idx] = {
+                              ...newItems[idx],
+                              label: newValue,
+                              ...(newItems[idx].children !== undefined
+                                ? { children: newValue }
+                                : {}),
+                              ...(newItems[idx].value !== undefined
+                                ? { value: newValue }
+                                : {}),
+                            };
+                          } else {
+                            newItems[idx] = newValue;
+                          }
+                          this.methods.updateKnob(name, newItems);
+                        }}
+                      />
+                      <UI.textarea
+                        label="Content"
+                        minRows={2}
+                        value={itemContent}
+                        onInput={(e) => {
+                          const newValue = e.currentTarget.value;
+                          const newItems = [...items];
+                          if (typeof newItems[idx] === "object") {
+                            newItems[idx] = {
+                              ...newItems[idx],
+                              content: newValue,
+                            };
+                          }
+                          this.methods.updateKnob(name, newItems);
+                        }}
+                      />
+                    </UI.flex>
+                  </UI.card>
+                );
+              })}
+              <UI.button
+                variant="outline"
+                size="xs"
+                onClick={() => {
+                  const newIdx = items.length;
+                  const newItem = {
+                    id: String(Date.now()),
+                    label: `Item ${newIdx + 1}`,
+                    content: `Item ${newIdx + 1} content`,
+                    children: `Item ${newIdx + 1}`,
+                    value: String(newIdx),
+                  };
+                  this.methods.updateKnob(name, [...items, newItem]);
+                }}
+              >
+                <UI.icon icon="add" />
+              </UI.button>
+            </UI.flex>
+          );
+        default:
+          return null;
+      }
+    },
+    toggleMobileMenu() {
+      this.state.mobileMenuOpened = !this.state.mobileMenuOpened;
+    },
+    closeMobileMenu() {
+      this.state.mobileMenuOpened = false;
+    },
+    setActiveTab(tab: "controls" | "actions" | "code" | "props") {
+      this.state.activeTab = tab;
+    },
+  },
+  lifecycle: {
+    async onMount() {
+      // Handle mobile detection
+      const handleResize = () => {
+        this.state.isMobile = window.innerWidth < 768;
+      };
+      handleResize();
+      window.addEventListener("resize", handleResize);
+      (this.refs as any)._handleResize = handleResize;
+
+      try {
+        this.state.loading = true;
+        this.state.error = null;
+
+        const allDefinitions: UIDefinition[] = [];
+
+        // 1. UI Primitives
+        if (this.props.ui) {
+          const uiDefs = await Promise.all(
+            Object.keys(this.props.ui).map(async (name) => {
+              try {
+                const { default: Comp } = (await import(
+                  `southpaw/ui/${name}`
+                )) as any;
+                return {
+                  params: Comp.params || {
+                    name,
+                    description: "",
+                    propsDef: {},
+                  },
+                  name,
+                  description: Comp.params?.description || "",
+                  examples: this.methods.extractExamples(name),
+                  category: this.methods.categorizeComponent(name, "ui"),
+                  library: "ui" as const,
+                };
+              } catch {
+                return this.methods.createFailedDefinition(name, "ui");
+              }
+            }),
+          );
+          allDefinitions.push(...uiDefs);
+        }
+
+        // 2. Blocks
+        if (this.props.blocks) {
+          const blockDefs = await Promise.all(
+            Object.keys(this.props.blocks).map(async (name) => {
+              try {
+                const { default: Comp } = (await import(
+                  `southpaw/ui/blocks/${name}`
+                )) as any;
+                return {
+                  params: Comp.params || {
+                    name,
+                    description: "",
+                    propsDef: {},
+                  },
+                  name,
+                  description: Comp.params?.description || "",
+                  examples: this.methods.extractExamples(name),
+                  category: this.methods.categorizeComponent(name, "blocks"),
+                  library: "blocks" as const,
+                };
+              } catch {
+                return this.methods.createFailedDefinition(name, "blocks");
+              }
+            }),
+          );
+          allDefinitions.push(...blockDefs);
+        }
+
+        // 3. Components
+        if (this.props.components) {
+          const compDefs = await Promise.all(
+            Object.keys(this.props.components).map(async (name) => {
+              try {
+                const { default: Comp } = (await import(
+                  `../../../src/components/${name}`
+                )) as any;
+                return {
+                  params: Comp.params || {
+                    name,
+                    description: "",
+                    propsDef: {},
+                  },
+                  name,
+                  description: Comp.params?.description || "",
+                  examples: this.methods.extractExamples(name),
+                  category: this.methods.categorizeComponent(
+                    name,
+                    "components",
+                  ),
+                  library: "components" as const,
+                };
+              } catch {
+                return this.methods.createFailedDefinition(name, "components");
+              }
+            }),
+          );
+          allDefinitions.push(...compDefs);
+        }
+
+        this.state.definitions = allDefinitions.sort((a, b) =>
+          a.name.localeCompare(b.name),
+        );
+      } catch (error) {
+        this.state.error = "Failed to load documentation libraries";
+        console.error("UIDocs loading error:", error);
+      } finally {
+        this.state.loading = false;
+      }
+    },
+    onUnmount() {
+      if ((this.refs as any)._handleResize) {
+        window.removeEventListener("resize", (this.refs as any)._handleResize);
+      }
+    },
+  },
+  render() {
+    const sectionId = this.router.query.section as string;
+    const activeDefinition = this.state.definitions.find(
+      (d: UIDefinition) => d.name === sectionId,
+    );
+
+    if (
+      activeDefinition &&
+      this.state.activeComponentId !== activeDefinition.name
+    ) {
+      this.methods.initializeKnobs(
+        activeDefinition.name,
+        activeDefinition.params.props || {},
+      );
+    }
+
+    const conceptsContent = (
+      <UI.flex
+        direction="column"
+        gap="xl"
+        p="xl"
+        style={{ maxWidth: 800, margin: "0 auto" }}
+      >
+        <UI.box>
+          <UI.title order={1} text="Southpaw UI" fz={48} fw={900} />
+          <UI.text
+            size="lg"
+            c="dimmed"
+            text="A modern, behavior-driven component library for high-performance web applications."
+          />
+        </UI.box>
+
+        <UI.grid gutter="xl" cells={[{ span: 6 }, { span: 6 }]}>
+          <UI.card withBorder p="xl" radius="md">
+            <UI.icon icon="bolt" c="yellow" fz={32} />
+            <UI.title order={3} text="Performance First" mt="md" />
+            <UI.text
+              size="sm"
+              c="dimmed"
+              mt="xs"
+              text="Lightweight components built with zero-overhead principles for lightning-fast interactions."
+            />
+          </UI.card>
+          <UI.card withBorder p="xl" radius="md">
+            <UI.icon icon="palette" c="blue" fz={32} />
+            <UI.title order={3} text="Design Tokens" mt="md" />
+            <UI.text
+              size="sm"
+              c="dimmed"
+              mt="xs"
+              text="Strict adherence to design tokens ensuring visual cohesion across your entire application."
+            />
+          </UI.card>
+        </UI.grid>
+
+        <UI.box mt="xl">
+          <UI.title order={2} text="Getting Started" />
+          <UI.text
+            mt="md"
+            text="Select a component from the sidebar to explore its props, see live examples, and copy implementation code."
+          />
+        </UI.box>
+      </UI.flex>
+    );
+
+    const sidebarContent = (
+      <>
+        <UI.flex p="md" align="center" gap="sm">
+          <UI.icon icon="architecture" fz={24} c="blue" />
+          <UI.text fw={700} text="UIDocs" fz="lg" />
+        </UI.flex>
+
+        <UI.box px="md" pb="sm">
+          <UI.textinput
+            placeholder="Search components..."
+            leftSection={<UI.icon icon="search" fz={16} />}
+            value={this.state.searchQuery}
+            onInput={(e) =>
+              this.methods.handleSearchChange(e.currentTarget.value)
+            }
+            size="xs"
+          />
+        </UI.box>
+
+        <UI.box style={{ flex: 1, overflowY: "auto" }} px="xs">
+          <UI.navlink
+            label="Introduction"
+            leftSection={<UI.icon icon="home" fz={18} />}
+            active={!sectionId || sectionId === "introduction"}
+            onClick={() => {
+              this.router.push("/ui?section=introduction");
+              this.state.mobileMenuOpened = false;
+            }}
+          />
+
+          {Object.entries(this.computed.categorizedDefinitions).map(
+            ([libKey, categories]) => {
+              const libraryLabels: Record<string, string> = {
+                ui: "UI Primitives",
+                blocks: "Page Blocks",
+                components: "App Components",
+              };
+
+              if (Object.keys(categories).length === 0) return null;
+
+              return (
+                <UI.box key={libKey}>
+                  <UI.divider
+                    my="xs"
+                    label={libraryLabels[libKey]}
+                    labelPosition="center"
+                    variant="dashed"
+                  />
+                  {Object.entries(categories).map(([category, defs]) => (
+                    <UI.box key={category}>
+                      <UI.navlink
+                        label={category}
+                        leftSection={<UI.icon icon="folder" fz={18} />}
+                        opened={this.state.expandedCategories.includes(
+                          category,
+                        )}
+                        onClick={() => this.methods.toggleCategory(category)}
+                      >
+                        {defs.map((def: UIDefinition) => (
+                          <UI.navlink
+                            key={def.name}
+                            label={def.name}
+                            active={sectionId === def.name}
+                            onClick={() => {
+                              this.router.push(`/ui?section=${def.name}`);
+                              this.state.mobileMenuOpened = false;
+                            }}
+                            pl="xl"
+                          />
+                        ))}
+                      </UI.navlink>
+                    </UI.box>
+                  ))}
+                </UI.box>
+              );
+            },
+          )}
+        </UI.box>
+      </>
+    );
+
+    const inspectorContent = activeDefinition ? (
+      <UI.tabs
+        value={this.state.activeTab}
+        onChange={(val) => this.methods.setActiveTab(val as any)}
+        style={{ flex: 1, display: "flex", flexDirection: "column" }}
+        tabs={[
+          {
+            value: "controls",
+            header: (
+              <UI.flex align="center" gap={4}>
+                <UI.icon icon="tune" fz={14} />
+                <UI.text size="xs" text="Controls" />
+              </UI.flex>
+            ),
+            content: (
+              <UI.box p="md" style={{ overflowY: "auto", flex: 1 }}>
+                <UI.flex direction="column" gap="md">
+                  {Object.entries(activeDefinition.params.propsDef || {}).map(
+                    ([name, def]) => (
+                      <UI.box key={name}>
+                        {this.methods.renderKnobInput(name, def as any)}
+                      </UI.box>
+                    ),
+                  )}
+                  {Object.keys(activeDefinition.params.propsDef || {})
+                    .length === 0 && (
+                    <UI.center h={100}>
+                      <UI.text
+                        size="sm"
+                        c="dimmed"
+                        fs="italic"
+                        text="No controls available"
+                      />
+                    </UI.center>
+                  )}
+                </UI.flex>
+              </UI.box>
+            ),
+          },
+          {
+            value: "actions",
+            header: (
+              <UI.flex align="center" gap={4}>
+                <UI.icon icon="dynamic_form" fz={14} />
+                <UI.text size="xs" text="Actions" />
+              </UI.flex>
+            ),
+            content: (
+              <UI.box p="md" style={{ overflowY: "auto", flex: 1 }}>
+                {this.state.actionLog.length === 0 ? (
+                  <UI.center h={100}>
+                    <UI.text
+                      size="sm"
+                      c="dimmed"
+                      fs="italic"
+                      text="No actions logged yet. Interact with the component."
+                    />
+                  </UI.center>
+                ) : (
+                  <UI.flex direction="column" gap="xs">
+                    {this.state.actionLog.slice(0, 20).map((log) => (
+                      <UI.card key={log.id} withBorder p="xs" radius="xs">
+                        <UI.flex justify="space-between">
+                          <UI.text
+                            fw={700}
+                            size="xs"
+                            text={log.name}
+                            c="blue"
+                          />
+                          <UI.text
+                            size="xs"
+                            c="dimmed"
+                            text={new Date(log.timestamp).toLocaleTimeString()}
+                          />
+                        </UI.flex>
+                        {log.data && log.data.length > 0 && (
+                          <UI.code
+                            code={JSON.stringify(log.data, null, 2)}
+                            codeLang="json"
+                            block
+                            mt="xs"
+                          />
+                        )}
+                      </UI.card>
+                    ))}
+                  </UI.flex>
+                )}
+              </UI.box>
+            ),
+          },
+          {
+            value: "code",
+            header: (
+              <UI.flex align="center" gap={4}>
+                <UI.icon icon="code" fz={14} />
+                <UI.text size="xs" text="Code" />
+              </UI.flex>
+            ),
+            content: (
+              <UI.box p="md" style={{ overflowY: "auto", flex: 1 }}>
+                {(() => {
+                  const propsCode = Object.entries(this.state.knobValues)
+                    .filter(
+                      ([key, value]) =>
+                        key !== "children" && value !== undefined,
+                    )
+                    .map(([key, value]) => {
+                      if (value === true) return key;
+                      if (value === false) return null;
+                      if (typeof value === "string") return `${key}="${value}"`;
+                      if (typeof value === "number") return `${key}={${value}}`;
+                      if (typeof value === "object")
+                        return `${key}={${JSON.stringify(value)}}`;
+                      return null;
+                    })
+                    .filter(Boolean);
+
+                  const propsString = propsCode.length
+                    ? `\n  ${propsCode.join("\n  ")}\n`
+                    : "";
+                  const childrenValue = this.state.knobValues["children"];
+                  const childrenCode =
+                    typeof childrenValue === "string" ? childrenValue : null;
+
+                  const code = childrenCode
+                    ? `<UI.${activeDefinition.name}${propsString}>\n  ${childrenCode}\n</UI.${activeDefinition.name}>`
+                    : `<UI.${activeDefinition.name}${propsString}/>`;
+
+                  return (
+                    <UI.box style={{ position: "relative" }}>
+                      <UI.code code={code} codeLang="tsx" block />
+                      <UI.actionicon
+                        size="sm"
+                        variant="subtle"
+                        style={{ position: "absolute", top: 8, right: 8 }}
+                        onClick={() => navigator.clipboard.writeText(code)}
+                      >
+                        <UI.icon icon="content_copy" fz={14} />
+                      </UI.actionicon>
+                    </UI.box>
+                  );
+                })()}
+              </UI.box>
+            ),
+          },
+          {
+            value: "props",
+            header: (
+              <UI.flex align="center" gap={4}>
+                <UI.icon icon="description" fz={14} />
+                <UI.text size="xs" text="Props" />
+              </UI.flex>
+            ),
+            content: (
+              <UI.box style={{ overflowY: "auto", flex: 1 }}>
+                <UI.table
+                  striped
+                  columns={["Prop", "Type", "Desc"]}
+                  rows={[
+                    ...this.methods
+                      .getCommonProps()
+                      .map((p) => [p.name, p.type, p.description]),
+                    ...this.methods
+                      .getComponentSpecificProps(activeDefinition)
+                      .map((p) => [p.name, p.type, p.description]),
+                  ]}
+                />
+              </UI.box>
+            ),
+          },
+        ]}
+      />
+    ) : (
+      <UI.center h="100%">
+        <UI.text c="dimmed" text="Select a component to inspect" />
+      </UI.center>
+    );
+
+    return (
+      <UI.flex
+        h="100vh"
+        direction="column"
+        style={{
+          overflow: "hidden",
+          backgroundColor: "var(--mantine-color-gray-0)",
+        }}
+      >
+        {/* MOBILE HEADER */}
+        {this.state.isMobile && (
+          <UI.flex
+            p="sm"
+            bg="white"
+            align="center"
+            justify="space-between"
+            style={{ borderBottom: "1px solid var(--mantine-color-gray-3)" }}
+          >
+            <UI.burger
+              opened={this.state.mobileMenuOpened}
+              onClick={() =>
+                (this.state.mobileMenuOpened = !this.state.mobileMenuOpened)
+              }
+              size="sm"
+            />
+            <UI.flex align="center" gap="xs">
+              <UI.icon icon="architecture" fz={20} c="blue" />
+              <UI.text fw={700} text="UIDocs" />
+            </UI.flex>
+            <UI.actionicon
+              variant="subtle"
+              onClick={() =>
+                (this.state.inspectorOpened = !this.state.inspectorOpened)
+              }
+            >
+              <UI.icon icon="tune" fz={20} />
+            </UI.actionicon>
+          </UI.flex>
+        )}
+
+        <UI.flex direction="row" flex={1} style={{ overflow: "hidden" }}>
+          {/* SIDEBAR */}
+          {this.state.isMobile ? (
+            <UI.drawer
+              opened={this.state.mobileMenuOpened}
+              onClose={() => (this.state.mobileMenuOpened = false)}
+              title="Navigation"
+              padding="md"
+              size="280px"
+            >
+              <UI.flex direction="column" h="100%">
+                {sidebarContent}
+              </UI.flex>
+            </UI.drawer>
+          ) : (
+            <UI.box
+              w={280}
+              h="100%"
+              style={{
+                borderRight: "1px solid var(--mantine-color-gray-3)",
+                backgroundColor: "white",
+                display: "flex",
+                flexDirection: "column",
+              }}
+            >
+              {sidebarContent}
+            </UI.box>
+          )}
+
+          {/* MAIN CANVAS */}
+          <UI.flex
+            direction="column"
+            flex={1}
+            h="100%"
+            style={{ position: "relative" }}
+          >
+            {activeDefinition ? (
+              <>
+                <UI.box
+                  style={{
+                    position: "absolute",
+                    top: this.state.isMobile ? 10 : 20,
+                    left: "50%",
+                    transform: "translateX(-50%)",
+                    zIndex: 100,
+                    backgroundColor: "rgba(255, 255, 255, 0.8)",
+                    backdropFilter: "blur(8px)",
+                    border: "1px solid var(--mantine-color-gray-3)",
+                    borderRadius: "var(--mantine-radius-xl)",
+                    padding: this.state.isMobile ? "2px 8px" : "4px 16px",
+                    boxShadow: "var(--mantine-shadow-md)",
+                    maxWidth: "95vw",
+                    overflow: "hidden",
+                  }}
+                >
+                  <UI.flex gap="xs" align="center">
+                    <UI.segmentedcontrol
+                      size={this.state.isMobile ? "xs" : "xs"}
+                      value={this.state.previewViewport}
+                      onChange={(val) => this.methods.setViewport(val)}
+                      data={[
+                        {
+                          label: <UI.icon icon="aspect_ratio" fz={16} />,
+                          value: "Responsive",
+                        },
+                        {
+                          label: <UI.icon icon="smartphone" fz={16} />,
+                          value: "375px",
+                        },
+                        {
+                          label: <UI.icon icon="tablet_mac" fz={16} />,
+                          value: "768px",
+                        },
+                        {
+                          label: <UI.icon icon="desktop_windows" fz={16} />,
+                          value: "1024px",
+                        },
+                      ]}
+                    />
+                    {!this.state.isMobile && (
+                      <>
+                        <UI.divider orientation="vertical" />
+                        <UI.actionicon
+                          variant="subtle"
+                          size="sm"
+                          onClick={() =>
+                            this.methods.setZoom(
+                              Math.max(0.25, this.state.previewZoom - 0.25),
+                            )
+                          }
+                        >
+                          <UI.icon icon="remove" fz={16} />
+                        </UI.actionicon>
+                        <UI.text
+                          size="xs"
+                          w={35}
+                          ta="center"
+                          text={`${Math.round(this.state.previewZoom * 100)}%`}
+                        />
+                        <UI.actionicon
+                          variant="subtle"
+                          size="sm"
+                          onClick={() =>
+                            this.methods.setZoom(
+                              Math.min(3, this.state.previewZoom + 0.25),
+                            )
+                          }
+                        >
+                          <UI.icon icon="add" fz={16} />
+                        </UI.actionicon>
+                        <UI.divider orientation="vertical" />
+                        <UI.actionicon
+                          variant={this.state.previewGrid ? "light" : "subtle"}
+                          size="sm"
+                          onClick={this.methods.toggleGrid}
+                          color={this.state.previewGrid ? "blue" : "gray"}
+                        >
+                          <UI.icon icon="grid_on" fz={16} />
+                        </UI.actionicon>
+                      </>
+                    )}
+                  </UI.flex>
+                </UI.box>
+
+                <UI.box
+                  style={{
+                    position: "absolute",
+                    bottom: this.state.isMobile ? 10 : 20,
+                    left: this.state.isMobile ? 10 : 20,
+                    zIndex: 100,
+                    backgroundColor: "rgba(255, 255, 255, 0.8)",
+                    backdropFilter: "blur(8px)",
+                    border: "1px solid var(--mantine-color-gray-3)",
+                    borderRadius: "var(--mantine-radius-md)",
+                    padding: "8px",
+                    boxShadow: "var(--mantine-shadow-sm)",
+                    maxWidth: this.state.isMobile ? "calc(100vw - 20px)" : 300,
+                  }}
+                >
+                  <UI.text
+                    size="xs"
+                    fw={700}
+                    c="dimmed"
+                    mb={4}
+                    text="Examples"
+                  />
+                  <UI.flex
+                    direction={this.state.isMobile ? "row" : "column"}
+                    gap={4}
+                    style={{ overflowX: "auto" }}
+                  >
+                    {activeDefinition.examples.map(
+                      (ex: string, idx: number) => {
+                        const UnstyledButtonComp = UI.unstyledbutton as any;
+                        return (
+                          <UnstyledButtonComp
+                            key={idx}
+                            onClick={() => this.methods.selectStory(idx)}
+                            style={
+                              {
+                                padding: "4px 8px",
+                                borderRadius: "var(--mantine-radius-xs)",
+                                backgroundColor:
+                                  this.state.activeStoryId === idx
+                                    ? "var(--mantine-color-blue-0)"
+                                    : "transparent",
+                                borderLeft:
+                                  !this.state.isMobile &&
+                                  this.state.activeStoryId === idx
+                                    ? "2px solid var(--mantine-color-blue-6)"
+                                    : "2px solid transparent",
+                                borderBottom:
+                                  this.state.isMobile &&
+                                  this.state.activeStoryId === idx
+                                    ? "2px solid var(--mantine-color-blue-6)"
+                                    : "2px solid transparent",
+                                cursor: "pointer",
+                                display: "block",
+                                whiteSpace: "nowrap",
+                              } as any
+                            }
+                          >
+                            <UI.text
+                              size="xs"
+                              fw={this.state.activeStoryId === idx ? 600 : 400}
+                              text={`Example ${idx + 1}`}
+                            />
+                          </UnstyledButtonComp>
+                        );
+                      },
+                    )}
+                  </UI.flex>
+                </UI.box>
+
+                <UI.box
+                  bg={this.state.previewTheme === "light" ? "white" : "#1A1B1E"}
+                  flex={1}
+                  style={{
+                    overflow: "auto",
+                    display: "flex",
+                    alignItems: "center",
+                    justifyContent: "center",
+                    position: "relative",
+                  }}
+                >
+                  <UI.box
+                    style={{
+                      transform: `scale(${this.state.previewZoom})`,
+                      transition: "transform 0.2s ease, width 0.3s ease",
+                      width:
+                        this.state.previewViewport === "Responsive"
+                          ? "100%"
+                          : this.state.previewViewport,
+                      padding: this.state.isMobile ? "40px 10px" : "60px",
+                      display: "flex",
+                      alignItems: "center",
+                      justifyContent: "center",
+                    }}
+                  >
+                    {(() => {
+                      const libData =
+                        activeDefinition.library === "ui"
+                          ? this.props.ui
+                          : activeDefinition.library === "blocks"
+                            ? this.props.blocks
+                            : this.props.components;
+
+                      const TargetComp = (libData as any)?.[
+                        activeDefinition.name
+                      ];
+
+                      if (!TargetComp)
+                        return (
+                          <UI.flex direction="column" align="center" gap="md">
+                            <UI.icon icon="error_outline" fz={48} c="red" />
+                            <UI.text
+                              text={`Component '${activeDefinition.name}' not found in ${activeDefinition.library}`}
+                              fw={700}
+                            />
+                            <UI.text
+                              size="xs"
+                              c="dimmed"
+                              text="This usually happens if the component was renamed or the import failed during the documentation scanning phase."
+                            />
+                          </UI.flex>
+                        );
+
+                      const propsWithLogging = { ...this.state.knobValues };
+                      Object.keys(propsWithLogging).forEach((key) => {
+                        if (
+                          key.startsWith("on") &&
+                          typeof propsWithLogging[key] === "function"
+                        ) {
+                          const original = propsWithLogging[key];
+                          propsWithLogging[key] = (...args: any[]) => {
+                            this.methods.logAction(key, args);
+                            original?.(...args);
+                          };
+                        }
+                      });
+
+                      return <TargetComp {...propsWithLogging} />;
+                    })()}
+                  </UI.box>
+
+                  {this.state.previewGrid && (
+                    <UI.box
+                      style={{
+                        position: "absolute",
+                        height: "300vh",
+                        inset: 0,
+                        pointerEvents: "none",
+                        zIndex: 10,
+                        backgroundImage: `linear-gradient(to right, ${
+                          this.state.previewTheme === "light"
+                            ? "var(--mantine-color-gray-4)"
+                            : "#2C2E33"
+                        } 1px, transparent 1px), linear-gradient(to bottom, ${
+                          this.state.previewTheme === "light"
+                            ? "var(--mantine-color-gray-4)"
+                            : "#2C2E33"
+                        } 1px, transparent 1px)`,
+                        backgroundSize: "20px 20px",
+                      }}
+                    />
+                  )}
+                </UI.box>
+              </>
+            ) : (
+              conceptsContent
+            )}
+          </UI.flex>
+
+          {/* INSPECTOR */}
+          {this.state.isMobile ? (
+            <UI.drawer
+              opened={this.state.inspectorOpened}
+              onClose={() => (this.state.inspectorOpened = false)}
+              title="Inspector"
+              padding="md"
+              size="lg"
+              position="right"
+            >
+              <UI.flex direction="column" h="100%">
+                {inspectorContent}
+              </UI.flex>
+            </UI.drawer>
+          ) : (
+            <UI.box
+              w={350}
+              h="100%"
+              style={{
+                borderLeft: "1px solid var(--mantine-color-gray-3)",
+                backgroundColor: "white",
+                display: "flex",
+                flexDirection: "column",
+              }}
+            >
+              {inspectorContent}
+            </UI.box>
+          )}
+        </UI.flex>
+      </UI.flex>
+    );
+  },
+});
+
+export default Component;