Xmszm Core

https://github.com/xmszm/core
Admin
A Vue 3 and Naive UI component library providing out-of-the-box configurable forms, tables, dialogs,...
Tokens:6,136
Snippets:23
Trust Score:3.1
Update:10 months ago
Show doc for...
Tokens:
Raw
### Install @xmszm/core and Peer Dependencies

Source: https://context7.com/xmszm/core/llms.txt

Installs the @xmszm/core library along with its required peer dependencies: Vue 3.3.0+, Naive UI 2.38.0+, Vue Router 4.2.0+, Dayjs 1.11.0+, lodash-es 4.17.21+, and @vicons/ionicons5 0.13.0+.

```bash
npm install @xmszm/core vue@^3.3.0 naive-ui@^2.38.0 vue-router@^4.2.0 dayjs@^1.11.0 lodash-es@^4.17.21 @vicons/ionicons5@^0.13.0
```

--------------------------------

### CommonQuery Component: Vue for Auto-Submit Query Forms

Source: https://context7.com/xmszm/core/llms.txt

The CommonQuery component simplifies creating query forms that auto-submit with debouncing. It uses Vue.js for its templating and script setup and integrates with Naive UI for buttons. The component accepts query parameters, options for form fields, and button configurations as props. It emits 'submit' and 'reset' events.

```vue
<template>
  <CommonQuery
    v-model:query="queryParams"
    :options="queryOptions"
    :btn="['reset', 'search']"
    @submit="handleSearch"
    @reset="handleReset"
  >
    <template #right-btn>
      <NButton type="primary" @click="handleExport">Export</NButton>
    </template>
  </CommonQuery>
</template>

<script setup>
import { ref } from 'vue'
import { CommonQuery } from '@xmszm/core'
import { NButton } from 'naive-ui'

const queryParams = ref({
  keyword: '',
  type: null,
  status: null,
  dateRange: []
})

const queryOptions = [
  {
    key: 'keyword',
    label: 'Keyword',
    way: 'input',
    props: {
      placeholder: 'Search by name or email',
      clearable: true
    }
  },
  {
    key: 'type',
    label: 'Type',
    way: 'select',
    options: [
      { label: 'All', value: null },
      { label: 'Admin', value: 'admin' },
      { label: 'User', value: 'user' }
    ],
    props: {
      clearable: true
    }
  },
  {
    key: 'status',
    label: 'Status',
    way: 'select',
    enum: {
      active: 'Active',
      inactive: 'Inactive',
      pending: 'Pending'
    }
  },
  {
    key: 'dateRange',
    label: 'Date Range',
    way: 'date-picker',
    props: {
      type: 'daterange',
      clearable: true
    }
  }
]

function handleSearch() {
  console.log('Search with params:', queryParams.value)
  // API call with queryParams
}

function handleReset() {
  console.log('Query reset')
  queryParams.value = { keyword: '', type: null, status: null, dateRange: [] }
}

function handleExport() {
  console.log('Export data with current query')
}
</script>
```

--------------------------------

### DataTable Component: Vue for Enhanced Table Display

Source: https://context7.com/xmszm/core/llms.txt

The DataTable component provides an enhanced table with features like sorting, filtering, and an operations column. It relies on Vue.js for its templating and script setup. The component accepts data, column definitions, pagination settings, and filtering options as props. It emits a 'sorted' event when the table is sorted.

```vue
<template>
  <DataTable
    :data="tableData"
    :columns="columns"
    :opr-columns="oprColumns"
    :pagination="pagination"
    :is-filter="true"
    :default-columns="['name', 'email']"
    @sorted="handleSort"
  />
</template>

<script setup>
import { ref, reactive } from 'vue'
import { DataTable, createActionColumnJsx } from '@xmszm/core'

const tableData = ref([
  { id: 1, name: 'Alice Johnson', email: 'alice@example.com', type: 'admin', status: 'active' },
  { id: 2, name: 'Bob Smith', email: 'bob@example.com', type: 'user', status: 'inactive' },
  { id: 3, name: 'Carol White', email: 'carol@example.com', type: 'user', status: 'active' }
])

const pagination = reactive({
  page: 1,
  pageSize: 10,
  pageCount: 1,
  itemCount: 3,
  showSizePicker: true,
  pageSizes: [10, 20, 50]
})

const columns = [
  {
    title: 'ID',
    key: 'id',
    width: 80,
    sorter: (row1, row2) => row1.id - row2.id
  },
  {
    title: 'Name',
    key: 'name',
    width: 160,
    sorter: true
  },
  {
    title: 'Email',
    key: 'email',
    width: 200
  },
  {
    title: 'Type',
    key: 'type',
    width: 120,
    render: (row) => {
      return row.type === 'admin' ? 'Administrator' : 'Standard User'
    }
  },
  {
    title: 'Status',
    key: 'status',
    width: 100
  }
]

const oprColumns = createActionColumnJsx(
  [
    {
      label: 'Edit',
      type: 'primary',
      permission: 'user:edit',
      onClick: (row, index) => {
        console.log('Edit row:', row)
        // Open edit dialog
      }
    },
    {
      label: 'Delete',
      type: 'error',
      permission: 'user:delete',
      mode: 'pop',
      isRender: (row) => row.status === 'inactive',
      onClick: (row, index) => {
        console.log('Delete row:', row)
        // Delete operation
      }
    },
    {
      label: 'View',
      type: 'info',
      onClick: (row, index) => {
        console.log('View row:', row)
      }
    }
  ],
  { fixed: 'right' },
  { max: 2, width: 80 } // Collapse actions beyond 2 into dropdown
)

function handleSort() {
  console.log('Table sorted, refetch data')
  // Trigger data refetch with new sort params
}
</script>
```

--------------------------------

### Implement Custom File Uploads with Upload Utilities

Source: https://context7.com/xmszm/core/llms.txt

The `@xmszm/core` library provides upload utilities, including `customUpload`, `getFileUrl`, and `setupConfig`, for managing file uploads with a custom request handler. The `setupConfig` function allows global configuration of the upload method, while `customUpload` handles the actual upload process, providing progress updates. `getFileUrl` is used to construct the full URL for uploaded files, optionally including processing parameters.

```javascript
import { customUpload, getFileUrl, setupConfig } from '@xmszm/core'
import axios from 'axios'

// Configure upload method globally
setupConfig({
  baseURL: 'https://api.example.com',
  uploadMethod: async (config) => {
    const formData = new FormData()
    formData.append('file', config.file)

    const response = await axios.post('/api/upload', formData, {
      headers: { 'Content-Type': 'multipart/form-data' },
      onUploadProgress: (progressEvent) => {
        const percent = Math.round((progressEvent.loaded * 100) / progressEvent.total)
        config.onProgress({ percent })
      }
    })

    return response.data
  }
})

// Use upload in component
async function handleUpload(file) {
  try {
    const result = await customUpload({
      file: file.file,
      onProgress: ({ percent }) => {
        console.log(`Upload progress: ${percent}%`)
      }
    })

    console.log('Upload successful:', result)
    const fileUrl = getFileUrl(result.url) // Prepends baseURL if needed
    console.log('Full URL:', fileUrl)

    // With OSS style parameter
    const thumbnailUrl = getFileUrl(result.url, 200) // Adds ?x-oss-process=style/w200
    console.log('Thumbnail URL:', thumbnailUrl)

    return fileUrl
  } catch (error) {
    console.error('Upload failed:', error)
    throw error
  }
}

```

--------------------------------

### JavaScript Route Metadata Initialization and API Configuration

Source: https://context7.com/xmszm/core/llms.txt

This JavaScript code demonstrates initializing route metadata, including permissions and API configurations, using the `initRouteMeta` function from '@xmszm/core'. It also shows how to use `useApiConfig` and `handleParams` to access and manipulate API endpoint URLs based on route metadata.

```javascript
import { createRouter, createWebHistory } from 'vue-router'
import { initRouteMeta } from '@xmszm/core'

const routes = [
  {
    path: '/users',
    title: 'User Management',
    component: () => import('./views/Users.vue'),
    permission: ['user:read'],
    auth: {
      list: '/api/users',
      create: '/api/users',
      update: '/api/users/{id}',
      delete: '/api/users/{id}'
    },
    api: {
      export: '/api/users/export',
      import: '/api/users/import'
    },
    children: [
      {
        path: 'detail/:id',
        title: 'User Detail',
        component: () => import('./views/UserDetail.vue'),
        permission: ['user:read', 'user:detail'],
        auth: {
          get: '/api/users/{id}',
          updateProfile: '/api/users/{id}/profile'
        }
      }
    ]
  },
  {
    path: '/settings',
    title: 'Settings',
    component: () => import('./views/Settings.vue'),
    hidden: true // Won't show in menu
  }
]

// Initialize route metadata
const processedRoutes = initRouteMeta(routes)

const router = createRouter({
  history: createWebHistory(),
  routes: processedRoutes
})

// Use in component
import { useApiConfig, handleParams } from '@xmszm/core'

function setupUserApi() {
  const api = useApiConfig() // Gets current route's API config

  // api.list = '/api/users'
  // api.create = '/api/users'
  // api.update = '/api/users/{id}'

  const userId = 123
  const updateUrl = handleParams(api.update, { '{id}': userId })
  // updateUrl = '/api/users/123'

  return { api, updateUrl }
}
```

--------------------------------

### Global Configuration for @xmszm/core

Source: https://context7.com/xmszm/core/llms.txt

Sets up global configurations for @xmszm/core, including API base URL, permission checking function, and upload method. It also allows for theme overrides for dialog components.

```javascript
// main.js
import { createApp } from 'vue'
import { setupConfig } from '@xmszm/core'
import '@xmszm/core/dist/style.css'
import axios from 'axios'

// Configure global settings
setupConfig({
  baseURL: 'https://api.example.com',
  hasPermission: (permission) => {
    const userPermissions = ['user:read', 'user:edit', 'admin:*']
    return userPermissions.includes(permission) || userPermissions.includes('admin:*')
  },
  uploadMethod: (config) => axios.request(config),
  dialog: {
    inheritTheme: true,
    themeOverrides: {
      common: {
        primaryColor: '#18a058'
      }
    }
  }
})

const app = createApp(App)
app.mount('#app')

```

--------------------------------

### JavaScript Table Ellipsis Configuration for Tooltips

Source: https://context7.com/xmszm/core/llms.txt

Demonstrates how to configure ellipsis for table columns using the `ellipsis` property from '@xmszm/core'. This allows for customizing the tooltip behavior, styles, and content when text is truncated due to column width limitations. The default `ellipsis` configuration provides a basic tooltip.

```javascript
import { ellipsis } from '@xmszm/core'

const columns = [
  {
    title: 'Description',
    key: 'description',
    width: 200,
    ellipsis: ellipsis // Default configuration with tooltip
  },
  {
    title: 'Custom Ellipsis',
    key: 'content',
    width: 150,
    ellipsis: {
      style: { cursor: 'pointer' },
      tooltip: {
        flip: true,
        arrowPointToCenter: true,
        contentStyle: {
          maxWidth: '500px',
          maxHeight: '400px',
          whiteSpace: 'pre-wrap'
        }
      }
    }
  }
]
```

--------------------------------

### DataForm Component Configuration

Source: https://context7.com/xmszm/core/llms.txt

Demonstrates the usage of the DataForm component from @xmszm/core. It shows how to define form fields, their types, validation rules, and props declaratively through an options array.

```vue
<template>
  <DataForm
    v-model:value="formValue"
    :options="formOptions"
    :form-props="{ labelWidth: '120px', labelPlacement: 'left' }"
  />
</template>

<script setup>
import { ref } from 'vue'
import { DataForm } from '@xmszm/core'

const formValue = ref({
  name: '',
  email: '',
  type: null,
  birthdate: null,
  description: ''
})

const formOptions = [
  {
    key: 'name',
    label: 'User Name',
    way: 'input',
    required: true,
    props: {
      placeholder: 'Enter name',
      maxlength: 50
    }
  },
  {
    key: 'email',
    label: 'Email',
    way: 'input',
    required: true,
    props: {
      type: 'email',
      placeholder: 'user@example.com'
    }
  },
  {
    key: 'type',
    label: 'User Type',
    way: 'select',
    required: true,
    options: [
      { label: 'Admin', value: 'admin' },
      { label: 'User', value: 'user' },
      { label: 'Guest', value: 'guest' }
    ]
  },
  {
    key: 'birthdate',
    label: 'Birth Date',
    way: 'date-picker',
    props: {
      type: 'date',
      format: 'yyyy-MM-dd'
    }
  },
  {
    key: 'description',
    label: 'Description',
    way: 'input',
    props: {
      type: 'textarea',
      rows: 4,
      placeholder: 'Enter description'
    }
  }
]
</script>

```

--------------------------------

### Register Custom Form Controls with @xmszm/core (JavaScript)

Source: https://context7.com/xmszm/core/llms.txt

Registers custom form control components, such as color pickers and rating inputs, with default properties. This allows for declarative use of these components within form configurations. It requires the '@xmszm/core' library and components from 'naive-ui'. The input is an object mapping custom keys to component definitions, and the output is the registration of these components for use in forms.

```javascript
import { setupOptions } from '@xmszm/core'
import { NColorPicker, NRate } from 'naive-ui'

setupOptions({
  'color-picker': {
    component: NColorPicker,
    defaultProps: {
      showAlpha: true,
      modes: ['hex', 'rgb']
    }
  },
  'rating': {
    component: NRate,
    defaultProps: {
      allowHalf: true,
      size: 'large'
    }
  }
})

// Use in form options
const formOptions = [
  {
    key: 'themeColor',
    label: 'Theme Color',
    way: 'color-picker',
    props: {
      defaultValue: '#18a058'
    }
  },
  {
    key: 'rating',
    label: 'Rating',
    way: 'rating',
    props: {
      count: 5
    }
  }
]
```

--------------------------------

### Implement Integrated Form Dialog with Validation using commonDialogMethod

Source: https://context7.com/xmszm/core/llms.txt

The `commonDialogMethod` from `@xmszm/core` allows for the creation of integrated form dialogs with built-in validation. It supports various modes such as 'add', 'edit', 'view', 'create', and 'delete', and accepts custom options for form fields and an `interfaceFn` for handling data submission. This method can be dynamically updated and is useful for user management interfaces.

```javascript
import { commonDialogMethod } from '@xmszm/core'
import { message } from 'naive-ui'

// Create user dialog
function openCreateUserDialog() {
  const { cancel, setValue, model } = commonDialogMethod(
    {
      title: 'User',
      mode: 'add', // 'add' | 'edit' | 'view' | 'create' | 'delete'
      options: [
        {
          key: 'name',
          label: 'Name',
          way: 'input',
          required: true,
          props: { placeholder: 'Enter name' }
        },
        {
          key: 'email',
          label: 'Email',
          way: 'input',
          required: true,
          props: { placeholder: 'user@example.com' }
        },
        {
          key: 'role',
          label: 'Role',
          way: 'select',
          required: true,
          options: [
            { label: 'Admin', value: 'admin' },
            { label: 'User', value: 'user' }
          ]
        }
      ],
      valueData: { name: '', email: '', role: 'user' },
      interfaceFn: async (data, { close, hideLoading }) => {
        try {
          // API call
          const response = await fetch('/api/users', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(data)
          })

          if (response.ok) {
            message.success('User created successfully')
            close()
            // Refresh table data
          } else {
            message.error('Failed to create user')
            hideLoading()
          }
        } catch (error) {
          message.error(error.message)
          hideLoading()
        }
      }
    },
    {
      style: { width: '600px' },
      closable: true,
      maskClosable: false
    }
  )

  // Dynamically update form values
  setTimeout(() => {
    setValue({ role: 'admin' })
  }, 1000)
}

// Edit user dialog
function openEditUserDialog(user) {
  commonDialogMethod({
    title: 'User',
    mode: 'edit',
    options: [
      { key: 'name', label: 'Name', way: 'input', required: true },
      { key: 'email', label: 'Email', way: 'input', required: true },
      { key: 'role', label: 'Role', way: 'select', required: true, options: [
        { label: 'Admin', value: 'admin' },
        { label: 'User', value: 'user' }
      ]}
    ],
    valueData: { ...user },
    interfaceFn: async (data, { close }) => {
      await fetch(`/api/users/${user.id}`, {
        method: 'PUT',
        body: JSON.stringify(data)
      })
      close()
    }
  })
}

// Read-only view dialog
function openViewUserDialog(user) {
  commonDialogMethod({
    title: 'User Details',
    mode: 'view', // Automatically sets read-only mode
    options: [
      { key: 'name', label: 'Name', way: 'input' },
      { key: 'email', label: 'Email', way: 'input' },
      { key: 'role', label: 'Role', way: 'input' },
      { key: 'createdAt', label: 'Created', way: 'input' }
    ],
    valueData: user
  })
}

```

--------------------------------

### JavaScript Array and Object Transformation Utilities

Source: https://context7.com/xmszm/core/llms.txt

Provides utility functions for transforming data between arrays and objects. `toArray` ensures a value is an array, `ArrayToObject` converts an array of objects into a lookup object keyed by a specified field, and `ObjectToArray` converts an object (like an enum) into an array of objects suitable for select options.

```javascript
import { toArray, ArrayToObject, ObjectToArray } from '@xmszm/core'

// toArray - ensure value is array
const single = 'item'
const multiple = ['item1', 'item2']
console.log(toArray(single))    // ['item']
console.log(toArray(multiple))  // ['item1', 'item2']

// ArrayToObject - convert array to lookup object
const users = [
  { label: 'Alice', value: 1, role: 'admin' },
  { label: 'Bob', value: 2, role: 'user' },
  { label: 'Carol', value: 3, role: 'user' }
]

const userLookup = ArrayToObject(users, {
  labelField: 'label',
  valueField: 'value'
})
// Result:
// {
//   '1': { label: 'Alice', value: 1, role: 'admin' },
//   '2': { label: 'Bob', value: 2, role: 'user' },
//   '3': { label: 'Carol', value: 3, role: 'user' }
// }

console.log(userLookup['1'].label) // 'Alice'
console.log(userLookup['2'].role)  // 'user'

// ObjectToArray - convert enum to select options
const statusEnum = {
  active: 'Active',
  inactive: 'Inactive',
  pending: 'Pending',
  suspended: { label: 'Suspended', color: 'red', disabled: true }
}

const statusOptions = ObjectToArray(statusEnum, {
  labelField: 'label',
  valueField: 'value'
})
// Result:
// [
//   { label: 'Active', value: 'active' },
//   { label: 'Inactive', value: 'inactive' },
//   { label: 'Pending', value: 'pending' },
//   { label: 'Suspended', value: 'suspended', color: 'red', disabled: true }
// ]

// Use in select
const formOptions = [
  {
    key: 'status',
    label: 'Status',
    way: 'select',
    options: statusOptions
  }
]
```

--------------------------------

### Vue Permission Directive for Element Visibility

Source: https://context7.com/xmszm/core/llms.txt

The v-core-permission directive in Vue.js allows controlling the visibility of HTML elements based on user permissions. It accepts a single permission string or an array of permission strings (any match will grant access). It's automatically registered when using DataForm, DataTable, or Options components.

```vue
<template>
  <div>
    <!-- Single permission -->
    <NButton v-core-permission="'user:edit'" type="primary">
      Edit User
    </NButton>

    <!-- Multiple permissions (any match) -->
    <NButton v-core-permission="['user:edit', 'admin:all']" type="error">
      Delete User
    </NButton>

    <!-- Complex example -->
    <div v-core-permission="'report:view'">
      <DataTable :data="reportData" :columns="reportColumns" />
    </div>
  </div>
</template>

<script setup>
import { NButton } from 'naive-ui'
import { DataTable } from '@xmszm/core'
// Permission directive auto-registers when using DataForm, DataTable, or Options components
</script>
```
Tokens:
Raw