Refactor: Centralize UI card component and add documentation
This commit introduces a new `NucleoDataCard.vue` component to centralize the common structure and styling of various card elements used throughout the UI. It also includes documentation for this new component. The following existing card components have been refactored to use `NucleoDataCard.vue`: - `ui/src/components/asistencias/cardAsistencia.vue` - `ui/src/components/empleados/cardEmpleado.vue` - `ui/src/components/planillas/cardPlanilla.vue` - `ui/src/components/tareas/cardTarea.vue` Key changes: - Created `NucleoDataCard.vue` in `ui/src/components/ui/` with flexible props (title, status, fields, accentColor, backgroundColor, avatarUrl, observation, showEditButton, showDeleteButton) and slots (header, body, footer, actions) to accommodate different card designs. - Updated `NucleoDataCard.vue` to directly use hex color values for `accentColor` and `backgroundColor` props for easier integration with your UI store. - Refactored the listed existing card components to utilize `NucleoDataCard.vue`, passing data through props and customizing specific sections (like avatars or field icons) via slots. - Ensured that all functionalities, including edit/delete actions and dynamic styling based on your UI store, are preserved in the refactored components. - Added `ui/src/components/ui/README.md` with detailed documentation for `NucleoDataCard.vue`, covering its purpose, props, slots, events, and a usage example. This centralization reduces code duplication, improves maintainability, and provides a consistent foundation for future card-based UI elements. The added documentation will help developers understand and use the new component effectively.
This commit is contained in:
google-labs-jules[bot]
96
ui/src/components/ui/README.md
Normal file
96
ui/src/components/ui/README.md
Normal file
@@ -0,0 +1,96 @@
|
||||
# UI Components
|
||||
|
||||
This directory contains general-purpose UI components used throughout the application.
|
||||
|
||||
## NucleoDataCard.vue
|
||||
|
||||
A flexible and centralized card component for displaying data entities.
|
||||
|
||||
### Purpose
|
||||
|
||||
The `NucleoDataCard` component provides a standardized way to display information in a card format. It's designed to be adaptable to various data types and styling requirements through props and slots. It supports a header (with optional avatar, title, and status), a body for displaying data fields and an optional observation section, and a footer with action buttons.
|
||||
|
||||
### Props
|
||||
|
||||
| Prop | Type | Default | Description |
|
||||
|---------------------|---------|-------------|-----------------------------------------------------------------------------|
|
||||
| `title` | String | _Required_ | The main title of the card, typically displayed in the header. |
|
||||
| `status` | String | `''` | A status string to be displayed as a badge in the header. |
|
||||
| `fields` | Array | `[]` | An array of objects (`{ label: String, value: String }`) for data rows. Each object represents a piece of data to be displayed with a label and its value. |
|
||||
| `accentColor` | String | `'#808080'` | Hex color code for the card's top border. |
|
||||
| `backgroundColor` | String | `'#FFFFFF'` | Hex color code for the card's background. |
|
||||
| `avatarUrl` | String | `''` | URL for an avatar image to be displayed in the header. |
|
||||
| `observation` | String | `''` | A text string for an observation section displayed below the fields. |
|
||||
| `showEditButton` | Boolean | `true` | Whether to display the default Edit button in the footer. |
|
||||
| `showDeleteButton` | Boolean | `true` | Whether to display the default Delete button in the footer. |
|
||||
|
||||
*Note: `accentColor` and `backgroundColor` are applied using inline styles. The default status badge styling in the header slot might not work as expected with hex `accentColor` values for its default Tailwind classes; use the `header` slot for custom status styling if needed.*
|
||||
|
||||
### Slots
|
||||
|
||||
- **`header`**: Allows custom content or layout for the card header. If used, it overrides the default header structure which includes the avatar, title, and status badge.
|
||||
- **`body`**: Allows complete customization of the main card content area. If used, you are responsible for rendering the content that would normally go here, such as iterating through the `fields` prop and displaying the `observation` prop. The default content of this slot handles the rendering of `fields` and `observation`.
|
||||
- **`footer`**: Allows custom content to be injected at the beginning of the card footer, before the `actions` slot and default Edit/Delete buttons.
|
||||
- **`actions`**: Allows adding custom buttons or other interactive elements to the footer. These are rendered before the default Edit and Delete buttons if they are visible.
|
||||
|
||||
### Events
|
||||
|
||||
- **`edit`**: Emitted with no payload when the default Edit button (if shown) is clicked.
|
||||
- **`delete`**: Emitted with no payload when the default Delete button (if shown) is clicked.
|
||||
|
||||
### Example Usage
|
||||
|
||||
```vue
|
||||
<template>
|
||||
<NucleoDataCard
|
||||
title="John Doe"
|
||||
status="Active"
|
||||
:fields="userDetails"
|
||||
accentColor="#3498db"
|
||||
backgroundColor="#f9f9f9"
|
||||
avatarUrl="path/to/avatar.jpg"
|
||||
observation="This user has been active for 3 years."
|
||||
:showEditButton="true"
|
||||
:showDeleteButton="true"
|
||||
@edit="onEditUser"
|
||||
@delete="onDeleteUser"
|
||||
>
|
||||
<template #actions>
|
||||
<button @click="viewMoreDetails" class="px-3 py-1 text-sm text-white bg-blue-500 rounded hover:bg-blue-600">
|
||||
View More
|
||||
</button>
|
||||
</template>
|
||||
</NucleoDataCard>
|
||||
</template>
|
||||
|
||||
<script setup>
|
||||
import NucleoDataCard from './NucleoDataCard.vue'; // Adjust path as needed
|
||||
import { ref } from 'vue';
|
||||
|
||||
const userDetails = ref([
|
||||
{ label: 'Email', value: 'john.doe@example.com' },
|
||||
{ label: 'Department', value: 'Engineering' },
|
||||
{ label: 'Role', value: 'Software Developer' },
|
||||
]);
|
||||
|
||||
const onEditUser = () => {
|
||||
console.log('Edit user event triggered');
|
||||
// Add logic to handle user editing
|
||||
};
|
||||
|
||||
const onDeleteUser = () => {
|
||||
console.log('Delete user event triggered');
|
||||
// Add logic to handle user deletion
|
||||
};
|
||||
|
||||
const viewMoreDetails = () => {
|
||||
console.log('View more details action triggered');
|
||||
// Add logic for custom action
|
||||
};
|
||||
</script>
|
||||
|
||||
<style scoped>
|
||||
/* Example of additional styling if needed for custom elements via slots */
|
||||
/* Tailwind CSS classes are generally preferred */
|
||||
</style>
|
||||
```
|
||||
Reference in New Issue
Block a user