Gx ComponentKit Development Guide

This guide explains how to extend and develop the Gx ComponentKit component library.

Project Structure

gx-componentkit/
├── src/
│   ├── components/          # UI Components
│   │   ├── GxModal.vue
│   │   ├── GxCountdown.vue
│   │   ├── GxVideoPlayer.vue
│   │   └── ...
│   ├── pages/              # Page Components
│   │   ├── GxPageStart.vue
│   │   ├── GxPageLoading.vue
│   │   └── ...
│   ├── composables/        # Vue Composables
│   │   ├── useMedia.ts
│   │   ├── useAnimations.ts
│   │   └── ...
│   ├── types/              # TypeScript Types
│   │   └── index.ts
│   └── index.ts           # Main entry point
├── example/               # Usage examples
├── dist/                 # Built library
└── README.md

Development Setup

1. Clone and Install

   git clone <repository-url>
   cd gx-componentkit
   npm install

2. Development Server

   npm run dev

3. Build Library

   npm run build

Adding New Components

1. Create Component File

Create a new .vue file in src/components/ or src/pages/:

<!-- src/components/GxNewComponent.vue -->
<template>
  <div class="gx-new-component">
    <!-- Component template -->
  </div>
</template>

<script setup lang="ts">
import type { Theme } from '@/types'

interface Props {
  // Define component props
  theme?: Theme
}

const props = withDefaults(defineProps<Props>(), {
  // Default values
})

const emit = defineEmits<{
  // Define component events
  'custom-event': [data: any]
}>()
</script>

<style scoped>
.gx-new-component {
  /* Component styles */
}
</style>

2. Export Component

Add the component to src/index.ts:

// Import
import GxNewComponent from './components/GxNewComponent.vue'

// Export
export { GxNewComponent }

// Register in plugin
const GxComponentKit = {
  install(app: App) {
    app.component('GxNewComponent', GxNewComponent)
    // ... other components
  }
}

3. Add TypeScript Types

If needed, add new types to src/types/index.ts:

export interface NewComponentProps {
  // Define interface
}

Adding New Composables

1. Create Composable File

Create a new file in src/composables/:

// src/composables/useNewFeature.ts
import { ref, computed } from 'vue'

export function useNewFeature() {
  const state = ref(false)
  
  const computedValue = computed(() => {
    return state.value ? 'active' : 'inactive'
  })
  
  const toggleState = () => {
    state.value = !state.value
  }
  
  return {
    state,
    computedValue,
    toggleState
  }
}

2. Export Composable

Add to src/index.ts:

export * from './composables/useNewFeature'

Component Guidelines

Naming Convention

• Components: GxComponentName (PascalCase with Gx prefix)
• Props: camelCase
• Events: kebab-case
• CSS Classes: gx-component-name (kebab-case with gx prefix)

Props Pattern

interface Props {
  // Required props first
  data: string
  
  // Optional props with defaults
  theme?: Theme
  variant?: 'primary' | 'secondary'
  disabled?: boolean
}

const props = withDefaults(defineProps<Props>(), {
  variant: 'primary',
  disabled: false
})

Events Pattern

const emit = defineEmits<{
  'update:modelValue': [value: string]
  'custom-event': [data: CustomData]
  'simple-event': []
}>()

Styling Guidelines

1. Use CSS Custom Properties for theming:

   .gx-component {
     background-color: var(--gx-primary-color, #007bff);
     color: var(--gx-text-color, #333);
   }

2. Follow BEM-like naming:

   .gx-component { }
   .gx-component__element { }
   .gx-component--modifier { }

3. Include responsive design:

   @media (max-width: 768px) {
     .gx-component {
       /* Mobile styles */
     }
   }

Converting from z-plugin-components

When converting components from the legacy z-plugin-components repository:

1. Update Component Structure

• Change from Options API to Composition API
• Add TypeScript types
• Update prop definitions
• Convert to <script setup>

2. Update Styling

• Add gx- prefix to CSS classes
• Convert to CSS custom properties for theming
• Ensure responsive design

3. Update Imports

• Change relative imports to use @/ alias
• Update composable imports

Example Conversion

Before (z-plugin-components):

<template>
  <div class="modal-wrapper">
    <!-- ... -->
  </div>
</template>

<script>
export default {
  props: {
    pluginVars: Object,
    theme: Object
  },
  // ...
}
</script>

After (gx-componentkit):

<template>
  <div class="gx-modal-wrapper">
    <!-- ... -->
  </div>
</template>

<script setup lang="ts">
import type { Theme, PluginVars } from '@/types'

interface Props {
  pluginVars: PluginVars
  theme?: Theme
}

const props = defineProps<Props>()
</script>

Testing

Component Testing

// tests/components/GxNewComponent.test.ts
import { mount } from '@vue/test-utils'
import GxNewComponent from '@/components/GxNewComponent.vue'

describe('GxNewComponent', () => {
  it('renders correctly', () => {
    const wrapper = mount(GxNewComponent, {
      props: {
        // test props
      }
    })
    
    expect(wrapper.find('.gx-new-component').exists()).toBe(true)
  })
})

Composable Testing

// tests/composables/useNewFeature.test.ts
import { useNewFeature } from '@/composables/useNewFeature'

describe('useNewFeature', () => {
  it('toggles state correctly', () => {
    const { state, toggleState } = useNewFeature()
    
    expect(state.value).toBe(false)
    toggleState()
    expect(state.value).toBe(true)
  })
})

Building and Publishing

Build Process

# Development build with watch
npm run build:watch

# Production build
npm run build

# Preview built library
npm run preview

Publishing

# Update version
npm version patch|minor|major

# Publish to npm
npm publish

Migration Checklist

When migrating components from z-plugin-components:

• Convert to TypeScript
• Update to Composition API
• Add proper prop types
• Update CSS class names with gx- prefix
• Add responsive design
• Update imports and exports
• Add to main index.ts
• Test component functionality
• Update documentation

Best Practices

1. Always use TypeScript for type safety
2. Follow Vue 3 Composition API patterns
3. Make components responsive by default
4. Use CSS custom properties for theming
5. Emit events for parent communication
6. Provide sensible defaults for props
7. Document component usage with examples
8. Test components thoroughly
9. Keep components focused on single responsibility
10. Use semantic HTML for accessibility