mozaic-mcp-server 2.1.1 → 2.3.0

package/skills/mozaic-freemarker-builder/skill.md

@@ -0,0 +1,145 @@
+# Mozaic Freemarker Builder
+
+Interactive Freemarker macro generator for Mozaic Design System. Help users discover, configure, and generate production-ready Freemarker template code with proper imports and configuration.
+
+## Activation
+
+This skill activates when users:
+- Ask about Freemarker components or macros
+- Want to generate Freemarker template code
+- Need help with Mozaic Freemarker implementation
+- Mention ".ftl" files or Freemarker templates
+
+## Workflow
+
+### 1. Discovery Phase
+Ask user what they want to build or which component they need:
+```bash
+# List all Freemarker components
+./scripts/list-components.sh all
+
+# List by category
+./scripts/list-components.sh form
+./scripts/list-components.sh navigation
+```
+
+### 2. Component Selection
+Let user browse and select:
+```bash
+# Search for specific component
+./scripts/search-components.sh "button"
+
+# Get detailed component info
+./scripts/get-component.sh "button"
+```
+
+### 3. Configuration
+Help user configure the component:
+- Show available configuration options (props)
+- Explain required vs optional parameters
+- Provide examples of common configurations
+
+### 4. Code Generation
+Generate ready-to-use Freemarker code:
+```bash
+# Generate basic code
+./scripts/generate-component.sh "button"
+
+# Generate with configuration
+./scripts/generate-component.sh "button" '{"color": "primary", "size": "m"}'
+
+# Generate with content
+./scripts/generate-component.sh "button" '{"color": "accent"}' "Click Me"
+```
+
+## Output Format
+
+Always provide:
+1. **Import statement** - Freemarker import directive
+2. **Configuration object** - <#assign config = {...}>
+3. **Macro invocation** - <@macroname.macroname config=config>...</@>
+4. **Installation info** - Maven dependency
+
+Example output:
+```ftl
+<#import "mozaic/button.ftl" as button>
+
+<#assign configButton = {
+    "color": "primary",
+    "size": "m",
+    "outlined": false
+}>
+
+<@button.button config=configButton>
+    Click Me
+</@button.button>
+```
+
+## Component Categories
+
+- **action**: Buttons, links, icon buttons
+- **form**: Text inputs, checkboxes, radio buttons, fields, file uploaders
+- **feedback**: Notifications, messages, badges, flags, loaders, progress bars, toasters, tooltips
+- **navigation**: Breadcrumbs, tabs, pagination, steppers, menus
+- **layout**: Containers, dividers, modals, drawers, accordions, popovers
+- **data-display**: Cards, tiles, images, avatars, logos, carousels, callouts, tags, ratings
+
+## Best Practices
+
+1. **Always import macros** at the top of .ftl files
+2. **Define configuration separately** using <#assign>
+3. **Use descriptive variable names** (e.g., configButton, configModal)
+4. **Set locale** with <#global locale="fr_FR"/> for i18n
+5. **Nested content** goes between opening and closing macro tags
+
+## Installation
+
+Maven dependency:
+```xml
+<dependency>
+    <groupId>com.adeo.mozaic</groupId>
+    <artifactId>mozaic-freemarker</artifactId>
+    <version>LATEST_VERSION</version>
+</dependency>
+```
+
+## Documentation
+
+Repository: https://github.com/adeo/mozaic-freemarker
+Design System: https://mozaic.adeo.cloud/
+
+## Example Interaction
+
+**User**: "I need a button for my Freemarker template"
+
+**Assistant**: "I'll help you create a button with Mozaic Freemarker. Let me show you the available options..."
+
+*Runs ./scripts/get-component.sh "button"*
+
+"Here are the button configuration options:
+- color: standard, accent, danger, ghost, inverse
+- size: s, m (default), l
+- outlined: boolean for outlined style
+- loading: boolean for loading state
+
+What style would you like?"
+
+**User**: "Primary colored, medium size"
+
+**Assistant**: *Generates code*
+
+"Here's your Freemarker button code:
+```ftl
+<#import "mozaic/button.ftl" as button>
+
+<#assign configButton = {
+    "color": "primary",
+    "size": "m"
+}>
+
+<@button.button config=configButton>
+    Click Me
+</@button.button>
+```
+
+This will render a primary-colored, medium-sized button. You can customize the text between the tags."

package/skills/mozaic-webcomponents-builder/scripts/generate-component.sh

@@ -0,0 +1,67 @@
+#!/bin/bash
+# Generate Web Component usage code
+# Usage: ./generate-component.sh <component-slug> [attributes-json] [children]
+
+COMPONENT_SLUG="$1"
+ATTRIBUTES_JSON="${2:-{}}"
+CHILDREN="$3"
+DB_PATH="${MOZAIC_DB_PATH:-${HOME}/.claude/mozaic.db}"
+
+if [ -z "$COMPONENT_SLUG" ]; then
+  echo "Error: Component slug required"
+  echo "Usage: $0 <component-slug> [attributes-json] [children]"
+  echo "Example: $0 button '{\"theme\":\"primary\",\"size\":\"m\"}' 'Click me'"
+  exit 1
+fi
+
+if [ ! -f "$DB_PATH" ]; then
+  echo "Error: Database not found at $DB_PATH"
+  echo "Please run: npx -p mozaic-mcp-server@latest adeo-mozaic-install-tools skills"
+  exit 1
+fi
+
+# Get component info
+COMPONENT_NAME=$(sqlite3 "$DB_PATH" <<EOF
+SELECT name FROM components
+WHERE slug = '$COMPONENT_SLUG'
+  AND frameworks LIKE '%webcomponents%'
+LIMIT 1;
+EOF
+)
+
+if [ -z "$COMPONENT_NAME" ]; then
+  echo "Error: Web Component '$COMPONENT_SLUG' not found"
+  exit 1
+fi
+
+# Generate import statement
+echo "// Import web component"
+echo "import '@adeo/mozaic-web-components/${COMPONENT_SLUG}.js';"
+echo ""
+echo "// Usage in HTML"
+
+# Build attributes string
+ATTRS=""
+if [ "$ATTRIBUTES_JSON" != "{}" ]; then
+  # Parse JSON and build attributes (simplified - in production use jq)
+  ATTRS=$(echo "$ATTRIBUTES_JSON" | sed 's/[{}"]//g' | sed 's/,/ /g' | sed 's/:/=/g')
+fi
+
+# Generate component tag
+TAG_NAME="$COMPONENT_SLUG"
+
+if [ -n "$CHILDREN" ]; then
+  if [ -n "$ATTRS" ]; then
+    echo "<${TAG_NAME} ${ATTRS}>"
+  else
+    echo "<${TAG_NAME}>"
+  fi
+  echo "  ${CHILDREN}"
+  echo "</${TAG_NAME}>"
+else
+  if [ -n "$ATTRS" ]; then
+    echo "<${TAG_NAME} ${ATTRS}></${TAG_NAME}>"
+  else
+    echo "<${TAG_NAME}></${TAG_NAME}>"
+  fi
+fi

package/skills/mozaic-webcomponents-builder/scripts/get-component.sh

@@ -0,0 +1,105 @@
+#!/bin/bash
+# Get detailed information about a Web Component
+# Usage: ./get-component.sh <component-slug>
+
+COMPONENT_SLUG="$1"
+DB_PATH="${MOZAIC_DB_PATH:-${HOME}/.claude/mozaic.db}"
+
+if [ -z "$COMPONENT_SLUG" ]; then
+  echo "Error: Component slug required"
+  echo "Usage: $0 <component-slug>"
+  echo "Example: $0 button"
+  exit 1
+fi
+
+if [ ! -f "$DB_PATH" ]; then
+  echo "Error: Database not found at $DB_PATH"
+  echo "Please run: npx -p mozaic-mcp-server@latest adeo-mozaic-install-tools skills"
+  exit 1
+fi
+
+COMPONENT_INFO=$(sqlite3 "$DB_PATH" <<EOF
+.mode json
+SELECT * FROM components
+WHERE slug = '$COMPONENT_SLUG'
+  AND frameworks LIKE '%webcomponents%'
+LIMIT 1;
+EOF
+)
+
+if [ -z "$COMPONENT_INFO" ] || [ "$COMPONENT_INFO" = "[]" ]; then
+  echo "Error: Web Component '$COMPONENT_SLUG' not found"
+  exit 1
+fi
+
+PROPS=$(sqlite3 "$DB_PATH" <<EOF
+.mode json
+SELECT name, type, default_value, required, description
+FROM component_props
+WHERE component_id = (
+  SELECT id FROM components WHERE slug = '$COMPONENT_SLUG' AND frameworks LIKE '%webcomponents%'
+)
+ORDER BY required DESC, name;
+EOF
+)
+PROPS="${PROPS:-[]}"
+
+SLOTS=$(sqlite3 "$DB_PATH" <<EOF
+.mode json
+SELECT name, description
+FROM component_slots
+WHERE component_id = (
+  SELECT id FROM components WHERE slug = '$COMPONENT_SLUG' AND frameworks LIKE '%webcomponents%'
+)
+ORDER BY name;
+EOF
+)
+SLOTS="${SLOTS:-[]}"
+
+EVENTS=$(sqlite3 "$DB_PATH" <<EOF
+.mode json
+SELECT name, payload, description
+FROM component_events
+WHERE component_id = (
+  SELECT id FROM components WHERE slug = '$COMPONENT_SLUG' AND frameworks LIKE '%webcomponents%'
+)
+ORDER BY name;
+EOF
+)
+EVENTS="${EVENTS:-[]}"
+
+EXAMPLES=$(sqlite3 "$DB_PATH" <<EOF
+.mode json
+SELECT title, code, description
+FROM component_examples
+WHERE component_id = (
+  SELECT id FROM components WHERE slug = '$COMPONENT_SLUG' AND frameworks LIKE '%webcomponents%'
+)
+  AND framework = 'webcomponents'
+ORDER BY id;
+EOF
+)
+EXAMPLES="${EXAMPLES:-[]}"
+
+CSS_CLASSES=$(sqlite3 "$DB_PATH" <<EOF
+.mode json
+SELECT class_name
+FROM component_css_classes
+WHERE component_id = (
+  SELECT id FROM components WHERE slug = '$COMPONENT_SLUG' AND frameworks LIKE '%webcomponents%'
+)
+ORDER BY class_name;
+EOF
+)
+CSS_CLASSES="${CSS_CLASSES:-[]}"
+
+cat <<EOF
+{
+  "component": $COMPONENT_INFO,
+  "attributes": $PROPS,
+  "slots": $SLOTS,
+  "events": $EVENTS,
+  "examples": $EXAMPLES,
+  "cssProperties": $CSS_CLASSES
+}
+EOF

package/skills/mozaic-webcomponents-builder/scripts/list-components.sh

@@ -0,0 +1,42 @@
+#!/bin/bash
+# List Web Components by category
+# Usage: ./list-components.sh [category]
+# Categories: form, navigation, feedback, layout, data-display, action, all (default)
+
+CATEGORY="${1:-all}"
+DB_PATH="${MOZAIC_DB_PATH:-${HOME}/.claude/mozaic.db}"
+
+# Check if database exists
+if [ ! -f "$DB_PATH" ]; then
+  echo "Error: Database not found at $DB_PATH"
+  echo "Please run: npx -p mozaic-mcp-server@latest adeo-mozaic-install-tools skills"
+  exit 1
+fi
+
+# Query components by category
+if [ "$CATEGORY" = "all" ]; then
+  sqlite3 "$DB_PATH" <<EOF
+.mode json
+SELECT
+  name,
+  slug,
+  category,
+  description
+FROM components
+WHERE frameworks LIKE '%webcomponents%'
+ORDER BY category, name;
+EOF
+else
+  sqlite3 "$DB_PATH" <<EOF
+.mode json
+SELECT
+  name,
+  slug,
+  category,
+  description
+FROM components
+WHERE frameworks LIKE '%webcomponents%'
+  AND category = '$CATEGORY'
+ORDER BY name;
+EOF
+fi

package/skills/mozaic-webcomponents-builder/scripts/search-components.sh

@@ -0,0 +1,34 @@
+#!/bin/bash
+# Search Web Components by name or description
+# Usage: ./search-components.sh <query>
+
+QUERY="$1"
+DB_PATH="${MOZAIC_DB_PATH:-${HOME}/.claude/mozaic.db}"
+
+if [ -z "$QUERY" ]; then
+  echo "Error: Search query required"
+  echo "Usage: $0 <query>"
+  echo "Example: $0 button"
+  exit 1
+fi
+
+if [ ! -f "$DB_PATH" ]; then
+  echo "Error: Database not found at $DB_PATH"
+  echo "Please run: npx -p mozaic-mcp-server@latest adeo-mozaic-install-tools skills"
+  exit 1
+fi
+
+sqlite3 "$DB_PATH" <<EOF
+.mode json
+SELECT name, slug, category, description
+FROM components
+WHERE frameworks LIKE '%webcomponents%'
+  AND (
+    name LIKE '%$QUERY%'
+    OR slug LIKE '%$QUERY%'
+    OR description LIKE '%$QUERY%'
+    OR category LIKE '%$QUERY%'
+  )
+ORDER BY name
+LIMIT 20;
+EOF

package/skills/mozaic-webcomponents-builder/skill.md

@@ -0,0 +1,292 @@
+---
+name: mozaic-webcomponents-builder
+description: Interactive Web Components generator with Mozaic Design System. Helps discover, configure, and generate production-ready native web components with proper imports and usage patterns.
+version: 1.0.0
+allowed-tools:
+  - Bash
+---
+
+# Mozaic Web Components Builder
+
+An interactive assistant for building framework-agnostic applications with Mozaic Design System Web Components by ADEO. This skill helps you discover components, understand their attributes and events, generate ready-to-use HTML/JavaScript code, and set up installation properly.
+
+## What This Skill Does
+
+1. **Discover Web Components**: Browse Mozaic web components by category (forms, navigation, feedback, etc.)
+2. **Interactive Selection**: Propose component combinations based on your needs
+3. **Generate Code**: Create complete HTML with JavaScript imports and proper attribute usage
+4. **Installation Guidance**: Provide npm/yarn commands and import strategies (module vs script tag)
+5. **Attributes & Events**: Help configure component attributes and set up event listeners
+6. **Slots & CSS Properties**: Guide on using slots for content projection and CSS custom properties for theming
+
+## Shell Scripts Used
+
+This skill uses shell scripts to query the local Mozaic database:
+- `list-components.sh` - Browse available web components by category
+- `get-component.sh` - Get detailed component information (attributes, slots, events, CSS properties)
+- `search-components.sh` - Search components by name or description
+- `generate-component.sh` - Generate web component usage code
+
+Database location: `~/.claude/mozaic.db`
+
+## When to Use This Skill
+
+Use this skill when you:
+- Need framework-agnostic UI components (vanilla JS, server-rendered apps, micro-frontends)
+- Want to build with native Web Components (Custom Elements v1)
+- Need components that work across frameworks (React, Vue, Angular, Svelte)
+- Are building progressive enhancement layers
+- Want to explore available Mozaic web components
+- Need help with component attributes, events, and slots
+- Want installation and import guidance for web components
+
+## Interactive Workflow
+
+### Step 1: Understanding Your Needs
+
+When you activate this skill, I'll ask:
+
+**"What type of web component do you need to build?"**
+
+Common options:
+- A) Form (inputs, selects, checkboxes, validation)
+- B) Navigation (tabs, breadcrumb, pagination, menu)
+- C) Modal/Dialog (overlay, confirmation, alert)
+- D) Button/Action (primary, secondary, with icons)
+- E) Layout (cards, containers, dividers)
+- F) Data Display (tables, lists, badges, tags)
+- G) Feedback (notifications, loaders, progress bars)
+- H) Other (describe your needs)
+
+### Step 2: Browse Available Components
+
+Based on your answer, I'll use the `list-components.sh` script to show relevant web components.
+
+**Example**:
+```
+For forms, Mozaic offers these web components:
+- mozaic-input (text, email, password fields)
+- mozaic-select (dropdowns with single/multiple selection)
+- mozaic-checkbox (checkbox with label)
+- mozaic-radio (radio button)
+- mozaic-toggle (switch control)
+- mozaic-textarea (multi-line text input)
+```
+
+### Step 3: Component Details
+
+I'll use the `get-component.sh` script to show:
+- Available attributes (HTML attributes and properties)
+- Slots for content projection
+- Custom events you can listen to
+- CSS custom properties for theming
+- Usage examples
+
+**Example**:
+```html
+<!-- mozaic-button Attributes -->
+<mozaic-button
+  theme="primary"        <!-- Theme: primary, secondary, tertiary -->
+  size="m"               <!-- Size: s, m, l -->
+  disabled="false"       <!-- Disabled state -->
+  icon-left="arrow"      <!-- Icon on left -->
+  full-width="false"     <!-- Full width button -->
+>
+  Click me
+</mozaic-button>
+
+<!-- Events -->
+button.addEventListener('mozaic-click', (e) => {
+  console.log('Button clicked!', e.detail);
+});
+
+<!-- CSS Custom Properties -->
+:root {
+  --mozaic-button-bg: #007bff;
+  --mozaic-button-text: #fff;
+  --mozaic-button-padding: 12px 24px;
+}
+```
+
+### Step 4: Propose Component Combinations
+
+I'll suggest 2-3 combinations that work well together:
+
+**Example for "Login Form"**:
+
+**Option 1: Simple Login Form**
+```html
+<!-- Import components -->
+<script type="module">
+  import '@adeo/mozaic-web-components/input.js';
+  import '@adeo/mozaic-web-components/button.js';
+</script>
+
+<!-- Usage -->
+<form id="login-form">
+  <mozaic-input
+    label="Email"
+    type="email"
+    name="email"
+    required="true"
+  ></mozaic-input>
+
+  <mozaic-input
+    label="Password"
+    type="password"
+    name="password"
+    required="true"
+  ></mozaic-input>
+
+  <mozaic-button theme="primary" type="submit">
+    Login
+  </mozaic-button>
+</form>
+```
+
+**Option 2: Enhanced Login with Validation & Events**
+```html
+<!-- Import components -->
+<script type="module">
+  import '@adeo/mozaic-web-components/input.js';
+  import '@adeo/mozaic-web-components/button.js';
+  import '@adeo/mozaic-web-components/checkbox.js';
+</script>
+
+<!-- Usage -->
+<form id="login-form">
+  <mozaic-input
+    id="email-input"
+    label="Email"
+    type="email"
+    name="email"
+    required="true"
+    error-message=""
+  ></mozaic-input>
+
+  <mozaic-input
+    id="password-input"
+    label="Password"
+    type="password"
+    name="password"
+    required="true"
+    error-message=""
+  ></mozaic-input>
+
+  <mozaic-checkbox
+    name="remember"
+    label="Remember me"
+  ></mozaic-checkbox>
+
+  <mozaic-button id="login-btn" theme="primary" type="submit">
+    Login
+  </mozaic-button>
+</form>
+
+<script>
+  const form = document.getElementById('login-form');
+  const emailInput = document.getElementById('email-input');
+  const passwordInput = document.getElementById('password-input');
+  const loginBtn = document.getElementById('login-btn');
+
+  // Listen to input changes
+  emailInput.addEventListener('mozaic-change', (e) => {
+    validateEmail(e.detail.value);
+  });
+
+  passwordInput.addEventListener('mozaic-change', (e) => {
+    validatePassword(e.detail.value);
+  });
+
+  // Form submission
+  form.addEventListener('submit', async (e) => {
+    e.preventDefault();
+    loginBtn.setAttribute('loading', 'true');
+
+    // Perform login
+    try {
+      await login(emailInput.value, passwordInput.value);
+    } finally {
+      loginBtn.setAttribute('loading', 'false');
+    }
+  });
+
+  function validateEmail(email) {
+    if (!email.includes('@')) {
+      emailInput.setAttribute('error-message', 'Invalid email format');
+      return false;
+    }
+    emailInput.removeAttribute('error-message');
+    return true;
+  }
+
+  function validatePassword(password) {
+    if (password.length < 8) {
+      passwordInput.setAttribute('error-message', 'Password must be at least 8 characters');
+      return false;
+    }
+    passwordInput.removeAttribute('error-message');
+    return true;
+  }
+</script>
+```
+
+**Option 3: Server-Side Rendered with Progressive Enhancement**
+```html
+<!-- SSR-friendly - works without JavaScript, enhanced with JS -->
+<form id="login-form" action="/login" method="POST">
+  <div class="form-field">
+    <label for="email">Email</label>
+    <input type="email" name="email" id="email" required>
+  </div>
+
+  <div class="form-field">
+    <label for="password">Password</label>
+    <input type="password" name="password" id="password" required>
+  </div>
+
+  <button type="submit">Login</button>
+</form>
+
+<!-- Progressive enhancement with web components -->
+<script type="module">
+  import '@adeo/mozaic-web-components/input.js';
+  import '@adeo/mozaic-web-components/button.js';
+
+  // Enhance form when components are loaded
+  customElements.whenDefined('mozaic-input').then(() => {
+    enhanceForm();
+  });
+
+  function enhanceForm() {
+    const form = document.getElementById('login-form');
+    // Replace native inputs with web components
+    // Web components will read existing values
+  }
+</script>
+```
+
+### Step 5: Refinement & Configuration
+
+You can:
+- Choose an option: "I like Option 2"
+- Customize: "Add a forgot password link"
+- Combine: "Use Option 1 but add event handling from Option 2"
+- Request changes: "Make the button full width"
+- Ask about features: "How do I add an icon to the button?"
+
+### Step 6: Generate Final Code
+
+I'll use the `generate-component.sh` script to create complete code with:
+- Import statements (ES modules or script tags)
+- Component usage with proper attributes
+- Event listener setup
+- CSS custom property theming
+- Accessibility attributes
+
+## Common Use Cases
+
+### 1. Creating a Contact Form
+
+```markdown
+User: "I need a contact form with name, email, and message fields"