@universal-interface/components/README.md

Universal Interface Components for Vue.js

# Universal Interface Components

A collection of Vue.js components for building admin interfaces and dashboards.

## Installation

```bash
npm install @universal-interface/components
```

## Usage

### As a Plugin

```javascript
import Vue from 'vue'
import ElementPlus from 'element-plus'
import UniversalInterface from '@universal-interface/components'

// Element Plus is required for these components
Vue.use(ElementPlus)
Vue.use(UniversalInterface)
```

### Individual Components

```javascript
import { Account, Order, Product } from '@universal-interface/components'

export default {
  components: {
    Account,
    Order,
    Product
  }
}
```

## Components

### View Components
- `Account` - Account management interface
- `Order` - Order management interface
- `Product` - Product management interface
- `Market` - Product market display
- `Template` - Template management interface
- `Canvas` - Canvas editor component
- `CanvasViewer` - Canvas viewer component
- `Detail` - Template detail view
- `Dashboard` - Dashboard overview
- `Login` - Login form
- `Users` - User management interface
- `Roles` - Role management interface
- `Consts` - Constants configuration interface
- `StatusExample` - Status constants usage example
- `AppView` - Main application view

### Layout Components
- `Layout` - Main layout container with sidebar and header
- `Sidebar` - Navigation sidebar with menu items
- `Breadcrumb` - Breadcrumb navigation with user dropdown

## Event Handling

Most components emit events for handling user interactions:

- `success` - When an operation completes successfully
- `error` - When an error occurs
- `confirm` - When user confirmation is required
- `warning` - When a warning should be displayed
- `info` - When informational messages should be displayed

Example:

```vue
<template>
  <Account 
    @success="handleSuccess"
    @error="handleError"
    @confirm="handleConfirm"
  />
</template>

<script>
import { Account } from '@universal-interface/components'

export default {
  components: { Account },
  methods: {
    handleSuccess(message) {
      this.$message.success(message)
    },
    handleError(message) {
      this.$message.error(message)
    },
    handleConfirm(config) {
      this.$confirm(config.message, config.title, {
        confirmButtonText: '确定',
        cancelButtonText: '取消',
        type: 'warning'
      }).then(() => {
        if (config.onConfirm) config.onConfirm()
      }).catch(() => {
        if (config.onCancel) config.onCancel()
      })
    }
  }
}
</script>
```

## API Integration

Components accept API implementations as props, allowing you to customize data fetching:

```vue
<template>
  <Account :account-api="customAccountApi" />
</template>

<script>
import { Account } from '@universal-interface/components'

export default {
  components: { Account },
  data() {
    return {
      customAccountApi: {
        list: (params) => {
          // Your custom implementation
          return Promise.resolve({ code: 200, data: { list: [], total: 0 } })
        },
        update: (data) => {
          // Your custom implementation
          return Promise.resolve({ code: 200, message: 'Success' })
        }
        // ... other methods
      }
    }
  }
}
</script>
```

## Layout Components Usage

Layout components can be used to create a complete admin interface:

```vue
<template>
  <Layout>
    <router-view />
  </Layout>
</template>

<script>
import { Layout } from '@universal-interface/components'

export default {
  components: { Layout }
}
</script>
```

The layout components accept props for customization:

```vue
<template>
  <Layout :sidebar-collapsed="sidebarCollapsed">
    <Sidebar 
      :routes="routes"
      :current-path="currentPath"
      :collapsed="sidebarCollapsed"
      @toggle-collapse="handleToggleCollapse"
      @menu-select="handleMenuSelect"
    />
    <Breadcrumb 
      :user-info="userInfo"
      :matched-routes="matchedRoutes"
      @logout="handleLogout"
      @profile="handleProfile"
    />
  </Layout>
</template>
```

## Building and Publishing to npm

### Prerequisites

Before building and publishing, ensure you have:

1. An npm account (create one at https://www.npmjs.com/signup if you don't have one)
2. Logged in to npm registry locally:
   ```bash
   npm login
   ```

### Building the Package

To build the package for distribution:

```bash
npm run build
```

This will:
- Compile all Vue components
- Generate three output formats:
  - ES Module (index.esm.js)
  - CommonJS (index.js)
  - UMD (index.min.js)
- Extract and bundle CSS styles
- Generate source maps for debugging

The built files will be located in the `dist/` directory.

### Publishing to npm

1. Update the version in `package.json`:
   ```bash
   npm version patch  # for bug fixes
   npm version minor  # for new features
   npm version major  # for breaking changes
   ```
   
   Or manually update the version field in `package.json`.

2. Publish the package:
   ```bash
   npm publish
   ```

   For scoped packages (like `@universal-interface/components`), make sure to set the access level:
   ```bash
   npm publish --access public
   ```

### Publishing to a Private Registry

If you want to publish to a private npm registry:

1. Set the registry URL:
   ```bash
   npm config set registry https://your-private-registry.com/
   ```

2. Publish as usual:
   ```bash
   npm publish
   ```

### Testing Before Publishing

To test the package locally before publishing:

1. Link the package:
   ```bash
   npm link
   ```

2. In another project, link to this package:
   ```bash
   npm link @universal-interface/components
   ```

3. Test the components in your project.

4. When finished testing, unlink:
   ```bash
   npm unlink @universal-interface/components
   ```

## Dependencies

This package depends on the following libraries:
- vue ^2.6.14
- element-plus ^2.4.0
- vue-cookies ^1.7.4
- vue-json-viewer ^2.2.22
- vuedraggable ^2.24.3

Make sure to install these dependencies in your project:

```bash
npm install vue element-plus vue-cookies vue-json-viewer vuedraggable
```

## Development

To run the example:

```bash
npm run example
```

To build the package:

```bash
npm run build
```

## License

MIT