@rio-cloud/uikit-mcp 1.0.0

package/data/pages/Utilities/utilities/usewindowresize.json

@@ -0,0 +1,63 @@
+{
+  "metadata": {
+    "captured_at": "2025-11-21T12:08:42.551Z",
+    "source": "https://uikit.developers.rio.cloud/#utilities/useWindowResize",
+    "category": "Utilities",
+    "section": "DOM behavior hooks",
+    "slug": "utilities/usewindowresize",
+    "version": "v1.13.2",
+    "hash_algorithm": "sha256",
+    "hash": "b97b8ecccd5beb527cbcae152064dce7daf3b691ba8e88fc159537fb4ad6b3dd"
+  },
+  "title": "useWindowResize",
+  "lead": "The useWindowResize hook allows to react on window size changes.",
+  "content": [
+    {
+      "heading": "useWindowResize",
+      "body": "",
+      "examples": [
+        {
+          "caption": "Example 1",
+          "rendered_html": "<div class=\"playground-content  bg-white padding-20 padding-bottom-25\" style=\"width: 100%;\"><div class=\"display-flex justify-content-center align-items-center\"><span>Width is more than 1024px</span></div></div>",
+          "tabs": [
+            {
+              "label": "React",
+              "language": "tsx",
+              "code": "import { useState } from 'react';\n\nimport useWindowResize from '@rio-cloud/rio-uikit/useWindowResize';\n\nexport default () => {\n    const getMessage = () => {\n        const windowWidth = window.innerWidth;\n\n        if (windowWidth < 1024 && windowWidth > 786) {\n            return 'Width is between 786px and 1024px';\n        } else if (windowWidth < 786) {\n            return 'Width is less than 786px';\n        } else if (windowWidth > 1024) {\n            return 'Width is more than 1024px';\n        }\n        return '';\n    };\n\n    const [message, setMessage] = useState(getMessage());\n\n    useWindowResize(() => {\n        setMessage(getMessage());\n    });\n\n    return (\n        <div className='display-flex justify-content-center align-items-center'>\n            <span>{message}</span>\n        </div>\n    );\n};"
+            },
+            {
+              "label": "HTML",
+              "language": "html",
+              "code": "<div class=\"display-flex justify-content-center align-items-center\">\n    <span>Width is more than 1024px</span>\n</div>"
+            },
+            {
+              "label": "Props",
+              "language": "json",
+              "code": null,
+              "props": [
+                {
+                  "heading": null,
+                  "rows": [
+                    {
+                      "name": "callback",
+                      "type": "Function",
+                      "default": "",
+                      "description": "The callback function to be triggered. The callback will be throttled by default."
+                    },
+                    {
+                      "name": "timeout",
+                      "type": "Number",
+                      "default": "300",
+                      "description": "The time in milliseconds to throttle the callback."
+                    }
+                  ]
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    }
+  ],
+  "see_also": []
+}

package/data/version.json

@@ -0,0 +1,4 @@
+{
+  "version": "v1.13.2",
+  "captured_at": "2025-11-21T12:08:49.786Z"
+}

package/docs/content-schema.md

@@ -0,0 +1,147 @@
+# UI Kit Content Capture Schema
+
+This document defines the structure we will use when extracting per-page documentation from the RIO UI Kit site. Each page we crawl will be normalised into a JSON artifact so the MCP server can serve rich, structured responses.
+
+## Output Location
+- All captured pages will be stored under `data/pages/<topNavLabel>/<slug>.json`.
+- Paths mirror the hash routes in the UI Kit SPA, e.g. `#components/button` → `data/pages/Components/button.json`.
+
+## JSON Structure
+```jsonc
+{
+  "metadata": {
+    "captured_at": "2025-10-28T13:26:10Z",
+    "source": "https://uikit.developers.rio.cloud/#components/button",
+    "category": "Components",          // top navigation label
+    "section": "Interaction",          // sidebar section title
+    "slug": "button",                  // hash route without leading namespace
+    "version": "v1.13.1",              // UI Kit version displayed in the top-right dropdown
+    "hash": "3d3a…",                   // content fingerprint (see below)
+    "hash_algorithm": "sha256"
+  },
+  "title": "Button",                   // main H1/H2 on the page
+  "lead": "Optional introductory text",
+  "content": [
+    {
+      "heading": "Available Variations",     // H2/H3 etc.
+      "body": "Concatenated paragraph text with inline formatting preserved as Markdown.",
+      "examples": [
+        {
+          "caption": "Default buttons",
+          "rendered_html": "<div>…</div>",    // sanitized outerHTML of rendered demo
+          "tabs": [
+            {
+              "label": "React",
+              "language": "tsx",
+              "code": "import { Button } from '@rio-cloud/rio-uikit'; …"
+            },
+            {
+              "label": "HTML",
+              "language": "html",
+              "code": "<button class=\"btn btn-default\">…</button>"
+            },
+            {
+              "label": "Props",
+              "language": "json",
+              "props": [
+                {
+                  "heading": "Button",
+                  "rows": [
+                    {
+                      "name": "variant",
+                      "type": "String",
+                      "default": "",
+                      "description": "Sets the button variant."
+                    }
+                  ]
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    }
+  ],
+  "see_also": [
+    {
+      "label": "Pager",
+      "href": "#components/pager"
+    }
+  ]
+}
+```
+
+### Notes
+- `metadata.section` comes from the sidebar group in `docs/navigation-inventory.json`. If a page is referenced from multiple sections, we capture the one encountered during traversal.
+- `metadata.version` reflects the UI Kit release selected in the site header when the page was captured.
+- `metadata.hash` / `metadata.hash_algorithm` store a SHA-256 fingerprint of the normalised output so repeated crawls can skip overwriting unchanged files.
+- `lead` is optional; we only include it when the page starts with descriptive paragraphs before the first heading.
+- `content` preserves H2/H3/H4 headings encountered in the main content area and associates following paragraphs/lists with that heading; layout-only noise (e.g. breakpoint width labels, loaders/spinners) is filtered out during capture.
+- `content[].examples[].rendered_html` preserves the demo markup so future renderers can show the live example. The field should be sanitized to avoid script/style injection.
+- `content[].examples[].tabs` captures each code tab available in the UI (`React`, `HTML`, `Classes`, `Props`). If a tab is missing, we omit it. `Props` tabs contain structured table data (`tabs[].props`) instead of raw JSON strings.
+- `content[].body` should be Markdown so the MCP server can return well-structured text to the LLM.
+- `see_also` is scraped from “See also …” link clusters when present.
+
+## Extraction Strategy
+1. Load each route collected in `docs/navigation-inventory.json`.
+2. Identify the primary title (`main h1/h2`).
+3. Walk the content area (excluding sidebar/footer) and gather headings, paragraphs, lists, and notes.
+4. For each demo block:
+   - Grab the rendered HTML container.
+   - Click through tab buttons (`[role="tab"]`, `.expander item header`) and record their code blocks.
+5. Sanitize code/HTML (trim, normalise indentation).
+6. Write the resulting JSON artifact to disk, overwriting existing files.
+7. Update `data/version.json` with the captured UI Kit version (`capture:all` writes this file) to skip redundant full re-crawls when the upstream version is unchanged.
+
+## Normalised Representation
+
+Downstream components (MCP server, search index) should not rely on the raw capture shape directly. Instead, use `server/lib/normalise-doc.mjs` to transform a raw artifact into the canonical structure defined in `server/lib/types.js`. The normaliser:
+
+- Derives `id` / `route` from `metadata.source` (`#components/button` → `components/button`).
+- Normalises Markdown and HTML into both Markdown and plaintext fields for easier search/indexing (`bodyMarkdown`, `bodyPlainText`, `plainText`).
+- Converts props tables into reusable Markdown blocks (`propsTables[].markdown`) while retaining the structured row data.
+- Aggregates a `summary` (lead paragraph or first content block) and `searchText` (title + lead + section body + props descriptions).
+- Exposes `loadDocumentation` (`server/lib/load-docs.mjs`) to traverse `data/pages/**`, normalise each JSON artifact, and return a `Map<id, UiKitDoc>` for server bootstrapping.
+- `searchText` is fed into a FlexSearch index (`server/lib/search-index.mjs`) that powers the `search_docs` MCP tool for keyword queries.
+
+Example (partial) output from `normaliseDocument(rawDoc)`:
+
+```jsonc
+{
+  "id": "components/button",
+  "route": "#components/button",
+  "category": "Components",
+  "title": "Button",
+  "summary": "The button component is the React equivalent to the normal HTML button…",
+  "sections": [
+    {
+      "heading": "Overview",
+      "bodyMarkdown": "…",
+      "bodyPlainText": "…",
+      "examples": [
+        {
+          "caption": "Standard buttons",
+          "plainText": "Standard buttons Default Primary …",
+          "codeTabs": [
+            { "label": "React", "language": "tsx", "code": "…" }
+          ],
+          "propsTables": [
+            {
+              "heading": null,
+              "markdown": "| Name | Type | Default | Description |…",
+              "rows": [ { "name": "disabled", "type": "Boolean", "default": "false", "description": "…" } ]
+            }
+          ]
+        }
+      ]
+    }
+  ],
+  "seeAlso": []
+}
+```
+
+## Open Questions / TODO
+- Determine whether to capture images as data URIs (likely not required initially).
+- Add validation tests to ensure schema compliance before publishing artifacts.
+- Consider a change-detection workflow so we can avoid re-processing unchanged pages during refresh runs.
+- Decide whether `loadDocumentation` should expose additional indices (e.g. grouped by category) or accept glob filters for selective loading.