@rio-cloud/uikit-mcp 1.0.0 → 1.1.0

package/dist/docs/utilities/useTimeout.md

@@ -0,0 +1,55 @@
+# useTimeout
+
+*Category:* Utilities
+*Section:* Lifecycle & execution hooks
+*Source:* https://uikit.developers.rio.cloud/#utilities/useTimeout
+*Captured:* 2025-12-12T12:39:37.822Z
+
+The useTimeout hook allows for executing some code after a specified amount of time.
+
+## useTimeout
+
+### Example: Example 1
+
+Message:...
+
+#### Summary
+
+Message:...
+
+#### React (tsx)
+
+```tsx
+import { useState } from 'react';
+
+import useTimeout from '@rio-cloud/rio-uikit/useTimeout';
+
+export default () => {
+    const [message, setMessage] = useState('...');
+
+    useTimeout(() => setMessage('Callback invoked'), 2000);
+
+    return (
+        <div className='display-flex flex-column justify-content-center align-items-center height-50'>
+            <label>Message:</label>
+            <div>{message}</div>
+        </div>
+    );
+};
+```
+
+#### HTML (html)
+
+```html
+<div class="display-flex flex-column justify-content-center align-items-center height-50">
+    <label>Message:</label>
+    <div>...</div>
+</div>
+```
+
+#### Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| callback | Function | — | The callback function to be triggered. |
+| delay | Number | — | The time to wait until the callback function gets invoked. |

package/dist/docs/utilities/useToggle.md

@@ -0,0 +1,115 @@
+# useToggle
+
+*Category:* Utilities
+*Section:* Lifecycle & execution hooks
+*Source:* https://uikit.developers.rio.cloud/#utilities/useToggle
+*Captured:* 2025-12-12T12:39:38.121Z
+
+The useToggle hook is a custom React hook for managing a boolean state. It provides an intuitive API to toggle, enable, or disable the value. You can optionally initialize it with a default state. Use it to handle toggle-based logic like switches, modals, or content visibility in your React components.
+
+## useToggle
+
+### Example: Example 1
+
+Usage on buttonsToggle is OFF
+ToggleEnableDisable
+Usage on a Switch component
+
+Usage for hiding contentHide content
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. In pharetra dui eget massa efficitur aliquam condimentum in felis. Integer eget metus vel nunc efficitur iaculis. Vivamus elementum ante et est sagittis semper. Ut consectetur enim nec tortor scelerisque tincidunt. Fusce ac ligula bibendum, rutrum libero quis, viverra sem. Interdum et malesuada fames ac ante ipsum primis in faucibus. Duis ut hendrerit massa, in molestie elit. Sed vitae orci ac purus volutpat posuere ac ut neque. Mauris ante orci, semper finibus lorem in, fringilla pretium velit.
+
+#### Summary
+
+Usage on buttonsToggle is OFF
+ToggleEnableDisable
+Usage on a Switch component
+
+Usage for hiding contentHide content
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. In pharetra dui eget massa efficitur aliquam condimentum in felis. Integer eget metus vel nunc efficitur iaculis. Vivamus elementum ante et est sagittis semper. Ut consectetur enim nec tortor scelerisque tincidunt. Fusce ac ligula bibendum, rutrum libero quis, viverra sem. Interdum et malesuada fames ac ante ipsum primis in faucibus. Duis ut hendrerit massa, in molestie elit. Sed vitae orci ac purus volutpat posuere ac ut neque. Mauris ante orci, semper finibus lorem in, fringilla pretium velit.
+
+#### React (tsx)
+
+```tsx
+import Button from '@rio-cloud/rio-uikit/Button';
+import useToggle from '@rio-cloud/rio-uikit/useToggle';
+import Switch from '@rio-cloud/rio-uikit/Switch';
+import Fade from '@rio-cloud/rio-uikit/Fade';
+import { dummyText } from '../../../utils/data';
+
+export default () => {
+    const { isToggled, toggle, enable, disable } = useToggle();
+
+    const { isToggled: isSwitchToggled, toggle: toggleSwitch } = useToggle(true);
+
+    const { isToggled: isContentShown, toggle: toggleContent } = useToggle(true);
+
+    const handleToggleButton = () => {
+        toggle(newValue => {
+            console.log(`Toggle changed to: ${newValue}`);
+            // Add some tracking here
+        });
+    };
+
+    return (
+        <div>
+            <label>Usage on buttons</label>
+            <p>Toggle is {isToggled ? 'ON' : 'OFF'}</p>
+            <div className='btn-toolbar'>
+                <Button onClick={handleToggleButton}>Toggle</Button>
+                <Button onClick={enable}>Enable</Button>
+                <Button onClick={disable}>Disable</Button>
+            </div>
+            <hr />
+            <label>Usage on a Switch component</label>
+            <Switch checked={isSwitchToggled} onChange={() => toggleSwitch()} />
+            <hr />
+            <label>Usage for hiding content</label>
+            <div>
+                <Button onClick={toggleContent}>{isContentShown ? 'Hide content' : 'Show content'}</Button>
+                <Fade show={isContentShown}>{dummyText}</Fade>
+            </div>
+        </div>
+    );
+};
+```
+
+#### HTML (html)
+
+```html
+<div>
+    <label>Usage on buttons</label>
+    <p>Toggle is OFF</p>
+    <div class="btn-toolbar">
+        <button type="button" class="btn btn-default btn-component" tabindex="0">Toggle</button>
+        <button type="button" class="btn btn-default btn-component" tabindex="0">Enable</button>
+        <button type="button" class="btn btn-default btn-component" tabindex="0">Disable</button>
+    </div>
+    <hr>
+    <label>Usage on a Switch component</label>
+    <div class="uikit-switch">
+        <label class="switch-label">
+            <input type="checkbox" class="switch-input" checked="">
+            <div class="switch-content" style="color: var(--brand-primary); min-width: 40px;">
+                <div class="switch-handle">
+                </div>
+            </div>
+        </label>
+    </div>
+    <hr>
+    <label>Usage for hiding content</label>
+    <div>
+        <button type="button" class="btn btn-default btn-component" tabindex="0">Hide content</button>
+        <div style="opacity: 1; transform: none;">
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit. In pharetra dui eget massa efficitur aliquam condimentum in felis. Integer eget metus vel nunc efficitur iaculis. Vivamus elementum ante et est sagittis semper. Ut consectetur enim nec tortor scelerisque tincidunt. Fusce ac ligula bibendum, rutrum libero quis, viverra sem. Interdum et malesuada fames ac ante ipsum primis in faucibus. Duis ut hendrerit massa, in molestie elit. Sed vitae orci ac purus volutpat posuere ac ut neque. Mauris ante orci, semper finibus lorem in, fringilla pretium velit.</div>
+    </div>
+</div>
+```
+
+#### Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| initialValue | Boolean | — | The initial state of the toggle. Defaults to false. |
+| toggle | Function | — | Toggles the current state between true and false. Accepts an optional callback function that executes after the state changes, receiving the new state as an argument. |
+| enable | Function | — | Sets the toggle state to true. |
+| disable | Function | — | Sets the toggle state to false. |

package/dist/docs/utilities/useWindowResize.md

@@ -0,0 +1,70 @@
+# useWindowResize
+
+*Category:* Utilities
+*Section:* DOM behavior hooks
+*Source:* https://uikit.developers.rio.cloud/#utilities/useWindowResize
+*Captured:* 2025-12-12T12:39:43.534Z
+
+The useWindowResize hook allows to react on window size changes.
+
+## useWindowResize
+
+### Example: Example 1
+
+Width is more than 1024px
+
+#### Summary
+
+Width is more than 1024px
+
+#### React (tsx)
+
+```tsx
+import { useState } from 'react';
+
+import useWindowResize from '@rio-cloud/rio-uikit/useWindowResize';
+
+export default () => {
+    const getMessage = () => {
+        const windowWidth = window.innerWidth;
+
+        if (windowWidth < 1024 && windowWidth > 786) {
+            return 'Width is between 786px and 1024px';
+        }
+        if (windowWidth < 786) {
+            return 'Width is less than 786px';
+        }
+        if (windowWidth > 1024) {
+            return 'Width is more than 1024px';
+        }
+        return '';
+    };
+
+    const [message, setMessage] = useState(getMessage());
+
+    useWindowResize(() => {
+        setMessage(getMessage());
+    });
+
+    return (
+        <div className='display-flex justify-content-center align-items-center'>
+            <span>{message}</span>
+        </div>
+    );
+};
+```
+
+#### HTML (html)
+
+```html
+<div class="display-flex justify-content-center align-items-center">
+    <span>Width is more than 1024px</span>
+</div>
+```
+
+#### Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| callback | Function | — | The callback function to be triggered. The callback will be throttled by default. |
+| timeout | Number | 300 | The time in milliseconds to throttle the callback. |

package/dist/index.mjs

@@ -0,0 +1,271 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import FlexSearch from "flexsearch";
+
+//#region server/lib/load-compiled.ts
+/**
+* Runtime loading of pre-compiled documentation data.
+*
+* Expects build artifacts in distRoot:
+* - doc-metadata.json (metadata for index + resource registry)
+* - search-synonyms.json
+* - version.json (optional)
+* - docs/*.md
+*/
+var BuildArtifactError = class extends Error {
+	constructor(missingFile, distRoot) {
+		super(`Build artifact missing: ${missingFile}\nExpected at: ${path.join(distRoot, missingFile)}\n\nRun "npm run build:server" to compile documentation first.\nIf you installed this package via npm, this is a packaging error.`);
+		this.name = "BuildArtifactError";
+	}
+};
+function readRequiredJson(distRoot, filename) {
+	const filePath = path.join(distRoot, filename);
+	if (!existsSync(filePath)) throw new BuildArtifactError(filename, distRoot);
+	try {
+		return JSON.parse(readFileSync(filePath, "utf8"));
+	} catch (error) {
+		throw new Error(`Failed to parse ${filename}: ${error instanceof Error ? error.message : error}`);
+	}
+}
+function loadCompiledData(distRoot) {
+	const metadata$1 = readRequiredJson(distRoot, "doc-metadata.json");
+	const synonyms$1 = readRequiredJson(distRoot, "search-synonyms.json");
+	let version$1 = null;
+	const versionPath = path.join(distRoot, "version.json");
+	if (existsSync(versionPath)) try {
+		version$1 = JSON.parse(readFileSync(versionPath, "utf8"));
+	} catch {}
+	return {
+		metadata: metadata$1,
+		synonyms: synonyms$1,
+		version: version$1
+	};
+}
+/** Markdown path is computed: docs/${id}.md */
+function getMarkdownPath(id) {
+	return `docs/${id}.md`;
+}
+function loadMarkdown(distRoot, id) {
+	const mdPath = getMarkdownPath(id);
+	const fullPath = path.join(distRoot, mdPath);
+	if (!existsSync(fullPath)) throw new Error(`Markdown file not found: ${mdPath}\nExpected at: ${fullPath}\nThis may indicate an incomplete build. Run "npm run build:server" to regenerate.`);
+	return readFileSync(fullPath, "utf8");
+}
+
+//#endregion
+//#region server/lib/search-index.ts
+/**
+* Build search index from pre-compiled metadata entries.
+* The boost field is already computed at build time.
+*/
+function buildSearchIndex(entries) {
+	const index = new FlexSearch.Document({
+		document: {
+			id: "id",
+			index: [
+				{
+					field: "title",
+					tokenize: "forward"
+				},
+				{
+					field: "lead",
+					tokenize: "forward"
+				},
+				{
+					field: "summary",
+					tokenize: "forward"
+				},
+				{
+					field: "searchText",
+					tokenize: "forward"
+				},
+				{
+					field: "boost",
+					tokenize: "forward"
+				}
+			],
+			store: [
+				"id",
+				"title",
+				"summary",
+				"category",
+				"section"
+			]
+		},
+		tokenize: "forward"
+	});
+	for (const entry of entries) index.add({
+		id: entry.id,
+		title: entry.title,
+		lead: entry.lead ?? "",
+		summary: entry.summary,
+		searchText: entry.searchText,
+		boost: entry.boost,
+		category: entry.category ?? "",
+		section: entry.section ?? ""
+	});
+	const search = (query, options) => {
+		return index.search(query, options).map((group) => ({
+			field: group.field,
+			result: (group.result ?? []).map((id) => String(id))
+		}));
+	};
+	return { search };
+}
+
+//#endregion
+//#region package.json
+var version = "1.1.0";
+
+//#endregion
+//#region server/index.ts
+const DIST_ROOT = import.meta.dirname;
+const { metadata, synonyms, version: capturedVersionInfo } = loadCompiledData(DIST_ROOT);
+const CAPTURED_UIKIT_VERSION = capturedVersionInfo?.version ?? null;
+const metadataById = new Map(metadata.map((m) => [m.id, m]));
+const server = new McpServer({
+	name: "uikit-mcp-server",
+	version
+}, { instructions: `UI Kit MCP usage guidelines:
+- Always discover documentation with search_docs; listResources is a static inventory and must not be used for guessing. Call readResource on the returned uikit-doc:// URI before using anything.
+- Coding rules: import components from '@rio-cloud/rio-uikit', prefer styling via provided classes instead of custom CSS files, and wrap the app/content in ApplicationLayout.
+- Follow documented props tables and examples; avoid inventing undocumented variants.
+- Treat the captured metadata (Category, Section, Captured) as the source of truth.
+- Captured UI Kit version: ${CAPTURED_UIKIT_VERSION ?? "unknown"}` });
+function buildResourceUri(docId) {
+	return new URL(`uikit-doc://${docId}`);
+}
+function expandDomainSynonyms(rawQuery, config) {
+	const query = rawQuery.toLowerCase();
+	const expansions = /* @__PURE__ */ new Set();
+	const preferred = /* @__PURE__ */ new Set();
+	const hints = /* @__PURE__ */ new Set();
+	for (const [key, values] of Object.entries(config.synonyms ?? {})) if (query.includes(key.toLowerCase())) {
+		(values ?? []).forEach((value) => {
+			if (value.toLowerCase() !== query) expansions.add(value);
+		});
+		(config.preferredDocIds?.[key] ?? []).forEach((id) => preferred.add(id));
+		if (config.hints?.[key]) hints.add(config.hints[key]);
+	}
+	return {
+		expansions: Array.from(expansions),
+		preferredDocIds: Array.from(preferred),
+		hints: Array.from(hints)
+	};
+}
+function registerDocResources(docs) {
+	for (const doc of docs) {
+		const uri = buildResourceUri(doc.id);
+		server.registerResource(doc.id, uri.href, {
+			title: doc.title,
+			description: doc.summary,
+			mimeType: "text/markdown"
+		}, async () => {
+			const markdown = loadMarkdown(DIST_ROOT, doc.id);
+			const versionNote = CAPTURED_UIKIT_VERSION ? `\n\n> Captured UI Kit version: ${CAPTURED_UIKIT_VERSION}` : "";
+			return { contents: [{
+				uri: uri.href,
+				mimeType: "text/markdown",
+				text: markdown + versionNote
+			}] };
+		});
+	}
+	console.error(`Registered ${docs.length} documentation resources.`);
+}
+function registerSearchTool(index, metadataMap, synonymsConfig) {
+	const inputSchema = {
+		query: z.string().min(1, "Query is required"),
+		limit: z.number().int().min(1).max(20).optional()
+	};
+	const outputSchema = { results: z.array(z.object({
+		resource: z.string(),
+		title: z.string(),
+		summary: z.string().optional(),
+		category: z.string().nullish(),
+		section: z.string().nullish()
+	})) };
+	server.registerTool("search_docs", {
+		title: "Search UI Kit docs",
+		description: "Full-text search across the captured UI Kit documentation. Always call this before readResource; it is the only supported way to discover resource IDs.",
+		inputSchema,
+		outputSchema
+	}, async ({ query, limit = 5 }) => {
+		const searchQueue = [query];
+		const domainSynonyms = expandDomainSynonyms(query, synonymsConfig);
+		for (const extra of domainSynonyms.expansions) searchQueue.push(extra);
+		const seen = /* @__PURE__ */ new Set();
+		const resolved = [];
+		for (const id of domainSynonyms.preferredDocIds) {
+			if (seen.has(id)) continue;
+			const doc = metadataMap.get(id);
+			if (!doc) continue;
+			seen.add(id);
+			resolved.push({
+				resource: buildResourceUri(id).href,
+				title: doc.title,
+				summary: doc.summary,
+				category: doc.category,
+				section: doc.section
+			});
+			if (resolved.length >= limit) break;
+		}
+		for (const searchQuery of searchQueue) {
+			const hits = index.search(searchQuery, {
+				limit: Math.max(limit * 2, 10),
+				suggest: true
+			});
+			for (const group of hits) {
+				for (const id of group.result ?? []) {
+					const docId = String(id);
+					if (seen.has(docId)) continue;
+					seen.add(docId);
+					const doc = metadataMap.get(docId);
+					if (!doc) continue;
+					resolved.push({
+						resource: buildResourceUri(docId).href,
+						title: doc.title,
+						summary: doc.summary,
+						category: doc.category,
+						section: doc.section
+					});
+					if (resolved.length >= limit) break;
+				}
+				if (resolved.length >= limit) break;
+			}
+			if (resolved.length >= limit) break;
+		}
+		let text = resolved.length > 0 ? resolved.map((entry, idx) => `${idx + 1}. ${entry.title} (${entry.resource})${entry.summary ? `\n   ${entry.summary}` : ""}`).join("\n\n").concat("\n\nAlways call readResource on one of the URIs above instead of guessing component routes.") : `No matches for "${query}".`;
+		const uniqueHints = Array.from(new Set(domainSynonyms.hints.filter(Boolean)));
+		if (uniqueHints.length) text += `\n\n${uniqueHints.join("\n")}`;
+		if (CAPTURED_UIKIT_VERSION) text += `\n\nCaptured UI Kit version: ${CAPTURED_UIKIT_VERSION}. Read "How to use the UIKIT" → "Install the npm package" for installation details.`;
+		return {
+			structuredContent: { results: resolved },
+			content: [{
+				type: "text",
+				text
+			}]
+		};
+	});
+}
+async function main() {
+	const index = buildSearchIndex(metadata);
+	registerDocResources(metadata);
+	registerSearchTool(index, metadataById, synonyms);
+	const docIds = new Set(metadata.map((m) => m.id));
+	const missingPreferred = /* @__PURE__ */ new Set();
+	for (const ids of Object.values(synonyms.preferredDocIds ?? {})) for (const id of ids ?? []) if (!docIds.has(id)) missingPreferred.add(id);
+	if (missingPreferred.size) console.warn(`Warning: preferredDocIds not found in dataset: ${Array.from(missingPreferred).join(", ")}`);
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+}
+main().catch((error) => {
+	console.error(error);
+	process.exit(1);
+});
+
+//#endregion
+export {  };

package/dist/search-synonyms.json

@@ -0,0 +1,134 @@
+{
+  "synonyms": {
+    "install": [
+      "installation",
+      "setup",
+      "how to",
+      "howto",
+      "getting started"
+    ],
+    "version": [
+      "release"
+    ],
+    "button": [
+      "btn",
+      "cta",
+      "buttons"
+    ],
+    "dropdown": [
+      "select",
+      "combobox"
+    ],
+    "select": [
+      "dropdown",
+      "combobox"
+    ],
+    "table": [
+      "datagrid",
+      "grid"
+    ],
+    "datagrid": [
+      "table",
+      "grid"
+    ],
+    "form": [
+      "input",
+      "field"
+    ],
+    "modal": [
+      "dialog"
+    ],
+    "dialog": [
+      "modal"
+    ],
+    "toast": [
+      "alert",
+      "notification"
+    ],
+    "alert": [
+      "toast",
+      "notification"
+    ],
+    "datepicker": [
+      "date picker",
+      "calendar"
+    ],
+    "date picker": [
+      "datepicker",
+      "calendar"
+    ],
+    "accordion": [
+      "expander"
+    ],
+    "expander": [
+      "accordion"
+    ],
+    "chip": [
+      "tag",
+      "badge"
+    ],
+    "tag": [
+      "chip",
+      "badge"
+    ]
+  },
+  "preferredDocIds": {
+    "install": [
+      "start/howto"
+    ],
+    "getting started": [
+      "start/howto"
+    ],
+    "setup": [
+      "start/howto"
+    ],
+    "version": [
+      "start/howto"
+    ],
+    "button": [
+      "components/button"
+    ],
+    "dropdown": [
+      "components/dropdowns"
+    ],
+    "select": [
+      "components/dropdowns"
+    ],
+    "table": [
+      "components/tables"
+    ],
+    "datagrid": [
+      "components/tables"
+    ],
+    "modal": [
+      "components/dialogs"
+    ],
+    "dialog": [
+      "components/dialogs"
+    ],
+    "toast": [
+      "components/notifications"
+    ],
+    "alert": [
+      "components/notifications"
+    ],
+    "datepicker": [
+      "components/datepickers"
+    ],
+    "date picker": [
+      "components/datepickers"
+    ],
+    "accordion": [
+      "components/expander"
+    ],
+    "expander": [
+      "components/expander"
+    ],
+    "chip": [
+      "components/tags"
+    ],
+    "tag": [
+      "components/tags"
+    ]
+  }
+}

package/dist/version.json

@@ -0,0 +1,4 @@
+{
+  "version": "2.0.0",
+  "captured_at": "2025-12-12T12:39:53.732Z"
+}