@trimble-oss/moduswebcomponents-mcp 1.0.0

package/versions/base/docs/modus-figma-mcp-integration-guide.mdx

@@ -0,0 +1,254 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="Documentation/Modus Figma MCP Integration Guide" />
+
+# Modus Figma MCP Integration Guide
+
+### Important Note
+
+**Designer Collaboration is Critical**: The accuracy and effectiveness of this tool heavily depends on proper design setup in Figma. For optimal results, use the **Modus 2.0 component library** available in Figma rather than creating custom elements. While custom themes can still be applied, using the Modus 2.0 design system significantly improves component detection and mapping accuracy.
+
+## Overview
+
+This guide explains how to use the Modus Figma tools to convert Figma designs into Modus Web Components.
+
+1. [Workflow Setup](#workflow-setup)
+   - [MCP Server Configuration](#mcp-server-configuration)
+   - [JSON Configuration for MCP Setup](#json-configuration-for-mcp-setup)
+   - [Authentication Setup](#authentication-setup)
+2. [Available MCP Tools](#available-mcp-tools)
+   - [1. analyze_figma](#1-analyze_figma)
+   - [2. get_modus_component_data](#2-get_modus_component_data)
+3. [Implementation Workflows](#implementation-workflows)
+   - [Workflow 1: Complete Page Analysis](#workflow-1-complete-page-analysis)
+   - [Workflow 2: Component-Specific Analysis](#workflow-2-component-specific-analysis)
+4. [Using the Specification File](#using-the-specification-file)
+
+## Workflow Setup
+
+### MCP Server Configuration
+
+The MCP server is accessible at:
+
+```
+https://flows-webhook.stage.trimble-ai.com/mcp/agentic/n8n-server/v1/modus
+```
+
+### JSON Configuration for MCP Setup
+
+Add the following JSON code to your AI environment's MCP configuration file (e.g., mcp.json in Cursor/VS Code) for access:
+
+```json
+"modus_n8n_webhook": {
+  "command": "npx",
+  "args": [
+    "mcp-remote",
+    "https://flows-webhook.stage.trimble-ai.com/mcp/agentic/n8n-server/v1/modus",
+    "--header",
+    "Authorization: Bearer ${AUTH_TOKEN}"
+  ],
+  "env": {
+    "AUTH_TOKEN": ""
+  }
+}
+```
+
+### Authentication Setup
+
+To access the MCP webhook, you need to create a Trimble Cloud application and generate an access token:
+
+1. **Subscribe to or Create an Application**: Follow the steps in the [Webhook Access Documentation](https://docs.trimblecloud.com/agentic-ai-platform/prototyping/how-tos/webhook-access/) to subscribe to an existing application or create a new one.
+
+2. **Generate Access Token**: Use the client ID and client secret from your application to generate an access token by following the [Access Token Generation Guide](https://docs.trimblecloud.com/profiles/docs/content/how-to-guides/prof-qstart-get-access-token/).
+
+3. **Configure Environment**: Use the generated access token as your AUTH_TOKEN in the MCP configuration:
+   ```
+   AUTH_TOKEN=your_generated_access_token_here
+   ```
+
+## Available MCP Tools
+
+### 1. analyze_figma
+
+**Purpose**: Enhanced Figma page analysis with advanced layout reconstruction and component mapping.
+
+**Parameters**:
+
+- `figma_url` (required): The Figma file URL
+- `node_id` (optional): Specific node ID to analyze, defaults to entire page
+
+**Returns** (example response structure):
+
+```json
+{
+  "success": true,
+  "file_key": "figma-file-key",
+  "node_id": "2100:41706",
+  "page_summary": {
+    "name": "Dashboard",
+    "layout_type": "dashboard",
+    "component_count": 156,
+    "has_navigation": true,
+    "has_sidebar": true,
+    "has_table": true,
+    "has_form": true,
+    "complexity": "high"
+  },
+  "key_components": [
+    {
+      "figma_name": "Navbar",
+      "figma_id": "I2100:41706;1:27669",
+      "modus_component": "modus-wc-navbar",
+      "component_type": "navbar",
+      "confidence": 0.95,
+      "detection_method": "pattern_match",
+      "properties": {},
+      "pattern": "navigation"
+    }
+  ],
+  "component_summary": {
+    "modus-wc-navbar": 2,
+    "modus-wc-button": 15,
+    "modus-wc-table": 1
+  },
+  "undetected_components": {
+    "count": 12,
+    "examples": [
+      {
+        "figma_name": "Custom Header",
+        "figma_id": "2100:123",
+        "reason": "Layout container"
+      }
+    ]
+  },
+  "implementation": {
+    "required_imports": ["ModusNavbar", "ModusButton", "ModusTable"],
+    "layout_approach": "dashboard",
+    "implementation_notes": [
+      "This is a dashboard layout with navigation",
+      "Include form validation for input elements",
+      "Consider lazy loading for complex components"
+    ]
+  },
+  "analysis_metadata": {
+    "detection_rate": "89.2%",
+    "total_mappings_available": 98,
+    "pipeline_nodes": 5
+  }
+}
+```
+
+### 2. get_modus_component_data
+
+**Purpose**: Retrieves comprehensive documentation for Modus Web Components.
+
+**Parameters**:
+
+- `component_name` (required): The Modus component name (e.g., 'modus-wc-table')
+
+**Returns** (example response structure):
+
+```json
+{
+  "success": true,
+  "component_documentation": {
+    "name": "modus-wc-table",
+    "properties": [
+      {
+        "name": "columns",
+        "type": "ModusTableColumn[]",
+        "required": true,
+        "description": "Array of column definitions"
+      }
+    ],
+    "events": [
+      {
+        "name": "cellClick",
+        "type": "CustomEvent<ModusTableCellClickEventDetails>",
+        "description": "Fires when a cell is clicked"
+      }
+    ],
+    "methods": [
+      {
+        "name": "sort",
+        "signature": "sort(columnId: string, direction: 'asc' | 'desc') => Promise<void>",
+        "description": "Sorts the table by specified column"
+      }
+    ],
+    "slots": [
+      {
+        "name": "default",
+        "description": "The table content"
+      }
+    ]
+  }
+}
+```
+
+## Implementation Workflows
+
+### Workflow 1: Complete Page Analysis
+
+**Purpose**: Analyze an entire Figma page and get comprehensive component mapping.
+
+**Input**:
+
+```json
+{
+  "figma_url": "https://www.figma.com/design/abc123/MyDesign?node-id=1-2",
+  "analyze_children": true
+}
+```
+
+**Steps**:
+
+1. **Initial Analysis**: Call analyze_figma with full page URL
+2. **Component Documentation**: For each unique component type found, call get_modus_component_data
+3. **Deep Dive Analysis**: For complex components, call analyze_figma with specific node IDs
+4. **Result Compilation**: Combine all analysis data into implementation guide
+
+### Workflow 2: Component-Specific Analysis
+
+**Purpose**: Deep dive into a specific component or section.
+
+**Input**:
+
+```json
+{
+  "figma_url": "https://www.figma.com/design/abc123/MyDesign",
+  "node_id": "2100:41706"
+}
+```
+
+**Steps**:
+
+1. **Targeted Analysis**: Call analyze_figma with specific node ID
+2. **Component Mapping**: Extract component types from analysis
+3. **Documentation Fetch**: Call get_modus_component_data for each component
+4. **Implementation Guide**: Generate specific implementation instructions
+
+## Using the Specification File
+
+To implement automated Figma-to-code conversion using these tools, attach the specification file to your AI conversation. This spec file contains detailed instructions for the AI on how to analyze Figma designs and generate Modus Web Components code.
+
+**How to use the spec file:**
+
+1. **Download the specification**: Get the [FIGMA_CODE_SPEC](https://docs.google.com/document/d/1OII7Yc0k2TIAtrUxYsYwPXtXNaO62wb2tU4-jYDnSnI/edit?tab=t.6m9dyidc3or1) file
+2. **Attach to your AI conversation**: Include the spec file when starting a new Figma analysis task
+3. **Provide your Figma URL**: Give the AI your Figma design URL
+4. **Follow the automated workflow**: The AI will use the spec file instructions to systematically analyze your design and generate implementation code
+
+**Example prompt:**
+
+```
+I want to convert my Figma design into Modus Web Components code.
+
+Figma URL: https://www.figma.com/design/your-figma-url-here
+Figma API Token: your-figma-api-token-here
+
+Please follow the attached specification file to analyze this design and generate the corresponding code with proper Modus components.
+```
+
+**Note**: You'll need to provide your Figma API token for the tools to access your Figma designs. You can generate a Figma API token from your Figma account settings.
+
+The AI will then use the Modus Figma tools through the specification's step-by-step process to deliver accurate, implementation-ready code.

package/versions/base/docs/modus-icon-usage.mdx

@@ -0,0 +1,210 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="Documentation/Modus Icon Usage" />
+
+# Modus Icon Usage
+
+Modus Web Components require Modus Icons.
+
+Starting from v0.0.0-beta.5, the Web Components package supports both outlined and solid icon variants through a single CSS file.
+
+## 1. Installation
+
+### Option A: Online Usage (CDN)
+
+Create a file at:
+
+```
+/public/modus-web-components/modus-icons.css
+```
+
+with the following contents:
+
+```css
+@font-face {
+  font-family: 'modus-icons';
+  src: url('https://cdn.jsdelivr.net/npm/@trimble-oss/modus-icons@1/dist/modus-outlined/fonts/modus-icons.woff2')
+    format('woff2');
+  font-style: normal;
+  font-weight: normal;
+  font-display: swap;
+}
+
+@font-face {
+  font-family: 'modus-icons-outlined';
+  src: url('https://cdn.jsdelivr.net/npm/@trimble-oss/modus-icons@1/dist/modus-outlined/fonts/modus-icons.woff2')
+    format('woff2');
+  font-style: normal;
+  font-weight: normal;
+  font-display: swap;
+}
+
+@font-face {
+  font-family: 'modus-icons-solid';
+  src: url('https://cdn.jsdelivr.net/npm/@trimble-oss/modus-icons@1/dist/modus-solid/fonts/modus-icons.woff2')
+    format('woff2');
+  font-style: normal;
+  font-weight: normal;
+  font-display: swap;
+}
+
+.modus-icons-outlined {
+  font-family: 'modus-icons-outlined';
+  font-style: normal;
+  font-weight: normal;
+}
+
+.modus-icons-solid {
+  font-family: 'modus-icons-solid';
+  font-style: normal;
+  font-weight: normal;
+}
+
+.modus-icons {
+  font-family: 'modus-icons';
+  font-style: normal;
+  font-weight: normal;
+}
+```
+
+Then include it in your app:
+
+```html
+<head>
+  <link rel="stylesheet" href="/modus-web-components/modus-icons.css" />
+</head>
+```
+
+### Option B: Offline Usage
+
+For applications requiring offline capability, follow these steps:
+
+1. Install the Modus Icons package:
+
+```bash
+npm install @trimble-oss/modus-icons
+```
+
+2. Download the font files:
+
+```
+node_modules/@trimble-oss/modus-icons/dist/modus-outlined/fonts/modus-icons.woff2
+node_modules/@trimble-oss/modus-icons/dist/modus-solid/fonts/modus-icons.woff2
+```
+
+3. Create this directory structure in your project:
+
+```
+public/
+  └── modus-web-components/
+      ├── fonts/
+      │   ├── modus-icons-outlined.woff2  (renamed from modus-outlined/fonts/modus-icons.woff2)
+      │   └── modus-icons-solid.woff2     (renamed from modus-solid/fonts/modus-icons.woff2)
+      └── modus-icons.css
+```
+
+4. Create a modified `modus-icons.css` file that references the local font files:
+
+```css
+@font-face {
+  font-family: 'modus-icons';
+  src: url('./fonts/modus-icons-outlined.woff2') format('woff2');
+  font-style: normal;
+  font-weight: normal;
+  font-display: swap;
+}
+
+@font-face {
+  font-family: 'modus-icons-outlined';
+  src: url('./fonts/modus-icons-outlined.woff2') format('woff2');
+  font-style: normal;
+  font-weight: normal;
+  font-display: swap;
+}
+
+@font-face {
+  font-family: 'modus-icons-solid';
+  src: url('./fonts/modus-icons-solid.woff2') format('woff2');
+  font-style: normal;
+  font-weight: normal;
+  font-display: swap;
+}
+
+.modus-icons-outlined {
+  font-family: 'modus-icons-outlined';
+  font-style: normal;
+  font-weight: normal;
+}
+
+.modus-icons-solid {
+  font-family: 'modus-icons-solid';
+  font-style: normal;
+  font-weight: normal;
+}
+
+.modus-icons {
+  font-family: 'modus-icons';
+  font-style: normal;
+  font-weight: normal;
+}
+```
+
+5. Include the CSS file in your HTML just as in the online version:
+
+```html
+<head>
+  <link rel="stylesheet" href="/modus-web-components/modus-icons.css" />
+</head>
+```
+
+## 2. Usage in Components
+
+Once the stylesheet is loaded, you can use icons in any framework:
+
+### Web Components
+
+```html
+<!-- Outlined icon (default) -->
+<modus-wc-icon name="alert" variant="outlined"></modus-wc-icon>
+
+<!-- Solid icon -->
+<modus-wc-icon name="alert" variant="solid"></modus-wc-icon>
+```
+
+### React
+
+```tsx
+import { ModusWcIcon } from '@trimble-oss/moduswebcomponents-react';
+
+export function IconExamples() {
+  return (
+    <div>
+      {/* Outlined */}
+      <ModusWcIcon name="alert" variant="outlined" />
+
+      {/* Solid */}
+      <ModusWcIcon name="alert" variant="solid" />
+
+      {/* Accessible icon */}
+      <ModusWcIcon
+        name="accessibility_circle"
+        variant="solid"
+        decorative={false}
+        aria-label="Accessibility features"
+      />
+
+      {/* Custom styling */}
+      <ModusWcIcon
+        name="add_bold"
+        variant="outlined"
+        decorative
+        style={{ color: 'var(--modus-wc-color-trimble-blue)' }}
+      />
+    </div>
+  );
+}
+```
+
+### Angular, Vue, etc.
+
+Follow the same approach — just make sure to include the global CSS file once in your application.

package/versions/base/docs/react.mdx

@@ -0,0 +1,129 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="Documentation/Frameworks/React" />
+
+# React Framework Integration
+
+This guide will help you get started with consuming the Modus React Web Component library in your React project.
+
+We highly recommend using the Modus React Components library for React based projects.
+These components are automatically generated using the Stencil React Framework Integration.
+
+Follow the steps outlined below to integrate and use Modus React Web Components effectively.
+
+Please refer to the [official stencil documentation](https://stenciljs.com/docs/react#consumer-usage) for more information on how to integrate with your React project.
+
+## Usage
+
+Modus React Components have a peer dependency with Modus Web Components and require the
+installation of both packages.
+
+### 1. Install `modus-wc-react`:
+
+Ensure that you specify the target version of React for the `modus-wc-react` package (e.g., `react18` for React 18).
+
+<b>
+  Lock the installed package versions to avoid unintended breakages on future
+  npm installs.
+</b>
+
+```bash
+npm install @trimble-oss/moduswebcomponents-react@<latest-version>-react<target-version>
+# e.g.,
+npm install @trimble-oss/moduswebcomponents-react@1.0.0-react18
+```
+
+### 2. Set up the styling:
+
+You will need to import our styling in your main JavaScript or CSS file:
+
+```js
+import '@trimble-oss/moduswebcomponents/modus-wc-styles.css';
+```
+
+### 3. Use the component library as normal.
+
+```tsx
+import { ModusWcBadge } from '@trimble-oss/moduswebcomponents-react';
+
+<ModusWcBadge aria-label="Badge" content="Words" />;
+```
+
+### Using the Controlled Input Pattern
+
+The controlled input pattern involves maintaining the state of the input's value within the React application or
+component. The [React Docs](https://react.dev/reference/react-dom/components/input#controlling-an-input-with-a-state-variable)
+describe this in more detail.
+
+```tsx
+import React, { useState } from 'react';
+import { ModusWcTextInput } from '@trimble-oss/moduswebcomponents-react';
+
+interface Props extends React.ComponentProps<typeof ModusWcTextInput> {}
+
+const MyComponent: React.FC<Props> = (props) => {
+  const [value, setValue] = useState('');
+
+  const handleInputChange = (
+    e: CustomEvent<HTMLModusWcTextInputElementEventMap['inputChange']>
+  ) => {
+    const value = e.detail.target.value;
+    setValue(value);
+  };
+
+  return (
+    <ModusWcTextInput
+      {...props}
+      onInputChange={handleInputChange}
+      value={value}
+    />
+  );
+};
+
+export default MyComponent;
+```
+
+### Wrapping Components
+
+When using Modus React Components directly, it is recommended to wrap it in corresponding React components within your application.
+This will abstract away from the library dependency, allowing more flexibility for you and your application in the future.
+
+Wrapped Modus component example:
+
+```tsx
+import React from 'react';
+import { ModusWcAvatar } from '@trimble-oss/moduswebcomponents-react';
+
+interface Props extends React.ComponentProps<typeof ModusWcAvatar> {}
+
+const Avatar: React.FC<Props> = (props) => {
+  return <ModusWcAvatar {...props} />;
+};
+
+export default Avatar;
+```
+
+or, a more complex wrapper:
+
+```tsx
+import React from 'react';
+import { ModusWcTextInput } from '@trimble-oss/moduswebcomponents-react';
+
+interface Props
+  extends Omit<React.ComponentProps<typeof ModusWcTextInput>, 'inputChange'> {
+  onValueChange: (value: string) => void;
+}
+
+const TextInput: React.FC<Props> = (props) => {
+  const handleInputChange = (
+    e: CustomEvent<HTMLModusWcTextInputElementEventMap['inputChange']>
+  ) => {
+    const value = e.detail.target.value;
+    props.onValueChange(value);
+  };
+
+  return <ModusWcTextInput {...props} onInputChange={handleInputChange} />;
+};
+
+export default TextInput;
+```

package/versions/base/docs/styling.mdx

@@ -0,0 +1,107 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="Documentation/Styling" />
+
+# Styling
+
+## Custom Styling
+
+The Modus Web Components library provides several ways to customize the appearance of components.
+
+### 1. Use a Theme
+
+Our components ship preloaded with several themes. A list of themes can be found
+[here](https://github.com/trimble-oss/modus-wc-2.0/blob/main/tailwind.config.ts)
+within the `daisyui.themes` array. Themes can be applied in multiple ways.
+
+#### a. Using the `ThemeSwitcher` component:
+
+The Theme Switcher will automatically handle theme switching through our theme store. Theme
+values are stored in local storage using the key `modus-theme-config`.
+
+```html
+<modus-wc-theme-provider initial-theme='{ "theme": "modus-modern-light" }'>
+  <modus-wc-theme-switcher aria-label="Toggle theme" />
+</modus-wc-theme-provider>
+```
+
+#### b. Manually applying the following HTML:
+
+```html
+<!-- Light theme -->
+<html class="light" data-theme="modus-modern-light" data-mode="light">
+  ...
+</html>
+
+<!-- Dark theme -->
+<html class="dark" data-theme="modus-modern-dark" data-mode="dark">
+  ...
+</html>
+```
+
+### 2. Override CSS Custom Properties
+
+Our components use CSS custom properties for styling. You can override these globally or at the component level.
+
+A full list of overridable CSS custom properties can be found
+[here](https://github.com/trimble-oss/modus-wc-2.0/blob/main/src/styles/variables.scss).
+
+```css
+:root {
+  --modus-wc-primary-color: purple;
+  --modus-wc-color-info: green;
+  --modus-wc-font-weight-normal: 500;
+}
+```
+
+```css
+.modus-wc-btn {
+  --modus-wc-border-radius-md: 20px;
+}
+```
+
+### 3. Use Custom CSS Classes
+
+Many components accept a `custom-class` attribute for additional styling:
+
+```html
+<modus-wc-button
+  label="Custom Button"
+  custom-class="my-custom-button"
+></modus-wc-button>
+```
+
+```css
+.my-custom-button {
+  background-color: purple;
+  border-color: purple;
+}
+```
+
+### 4. Apply Direct CSS Overrides
+
+Since Shadow DOM is disabled, you can directly target component classes.
+
+Our component classes are all prefixed with `modus-wc-` to avoid collisions.
+
+```css
+.modus-wc-btn {
+  background-color: yellow;
+  color: black;
+}
+```
+
+## CSS Reset (Tailwind Preflight)
+
+Tailwind performs a CSS reset (preflight) that normalizes browser styles to ensure all component styles are applied
+consistently across browsers. This reset is automatically loaded into applications consuming the library. We've
+provided Modus-specific overrides in `styles/tailwind.css` to maintain compatibility with our design system, though
+these overrides aren't exhaustive. If you need additional style adjustments, you can either:
+
+1. Add custom CSS overrides in your application
+2. Create a GitHub issue describing the needed override (contributions welcome)
+
+---
+
+Need help? Check out our [GitHub repository](https://github.com/trimble-oss/modus-wc-2.0)
+or [raise an issue](https://github.com/trimble-oss/modus-wc-2.0/issues).