fix(readme): Update readme with comprehensive reference documentation: add a usage snippet for components like DeesButton, introduce a detailed overview table of all component categories, and enhance documentation sections for each component group.
This commit is contained in:
parent
6c2f36f020
commit
3399004e75
@ -1,5 +1,13 @@
|
|||||||
# Changelog
|
# Changelog
|
||||||
|
|
||||||
|
## 2025-04-11 - 1.5.1 - fix(readme)
|
||||||
|
Update readme with comprehensive reference documentation: add a usage snippet for components like DeesButton, introduce a detailed overview table of all component categories, and enhance documentation sections for each component group.
|
||||||
|
|
||||||
|
- Added a code example showing how to import and use DeesButton.
|
||||||
|
- Introduced a components overview table that categorizes Core UI, Forms, Layout, Data Display, Visualization, Dialogs & Overlays, Navigation, and Development components.
|
||||||
|
- Expanded detailed documentation with usage examples for each component type.
|
||||||
|
- Reorganized content to improve clarity and ease of navigation for developers.
|
||||||
|
|
||||||
## 2025-04-11 - 1.5.0 - feat(badge)
|
## 2025-04-11 - 1.5.0 - feat(badge)
|
||||||
Add dees-badge component with demo file and update packageManager field in package.json
|
Add dees-badge component with demo file and update packageManager field in package.json
|
||||||
|
|
||||||
|
|||||||
336
readme.md
336
readme.md
@ -9,191 +9,215 @@ npm install @design.estate/dees-catalog
|
|||||||
```
|
```
|
||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
To use the components provided by `@design.estate/dees-catalog`, you need to import them into your project. Here's an example of how to import and use the `DeesButton` component:
|
||||||
### Overview
|
|
||||||
|
|
||||||
The `@design.estate/dees-catalog` is a powerful library that offers a suite of dynamic components designed for building sophisticated web applications. This library leverages modern web standards such as Web Components, and programming languages like JavaScript and TypeScript to provide developers with modular and reusable components. These components enhance the development workflow by offering ready-to-use solutions for UI design and interactivity, enabling developers to create intricate and functional applications efficiently.
|
|
||||||
|
|
||||||
Below, we will explore the diverse range of components available, demonstrating their integration and usage thoroughly within real-world scenarios. Each example will be crafted in TypeScript to ensure type safety and maintainable code. Let's navigate through the components by examining their setups, features, and potential applications in a comprehensive manner.
|
|
||||||
|
|
||||||
### Getting Started with Components
|
|
||||||
|
|
||||||
To use these components, you first need to import them into your project. Depending on your development environment, you might be using a module bundler that supports ES modules. In such cases, importing components is straightforward as demonstrated below:
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
import {
|
|
||||||
DeesButton,
|
|
||||||
DeesModal,
|
|
||||||
DeesTable,
|
|
||||||
DeesAppuiBase,
|
|
||||||
DeesForm,
|
|
||||||
DeesInputText,
|
|
||||||
DeesAppuiMainmenu,
|
|
||||||
DeesAppuiMainselector
|
|
||||||
} from '@design.estate/dees-catalog';
|
|
||||||
```
|
|
||||||
|
|
||||||
### Button Component: `DeesButton`
|
|
||||||
|
|
||||||
`DeesButton` is a versatile button component that can be configured for various UI needs such as form submissions, navigation actions, or interactive interfaces. It supports multiple styles including normal, highlighted, discreet, and status-based variations (e.g., pending, success, error).
|
|
||||||
|
|
||||||
#### Example Usage
|
|
||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
import { DeesButton } from '@design.estate/dees-catalog';
|
import { DeesButton } from '@design.estate/dees-catalog';
|
||||||
|
|
||||||
// Create a simple button
|
const button = document.createElement('dees-button');
|
||||||
const submitButton = document.createElement('dees-button');
|
button.text = 'Click me';
|
||||||
submitButton.text = 'Submit';
|
button.type = 'highlighted'; // Options: normal, highlighted, discreet
|
||||||
submitButton.type = 'highlighted';
|
button.status = 'pending'; // Options: normal, pending, success, error
|
||||||
|
|
||||||
// Add functionality
|
document.body.appendChild(button);
|
||||||
submitButton.addEventListener('clicked', () => {
|
|
||||||
console.log('Submit button clicked!');
|
|
||||||
});
|
|
||||||
document.body.appendChild(submitButton);
|
|
||||||
|
|
||||||
// Handling status change
|
|
||||||
async function handleFormSubmission() {
|
|
||||||
submitButton.status = 'pending';
|
|
||||||
try {
|
|
||||||
await simulateNetworkRequest();
|
|
||||||
submitButton.status = 'success';
|
|
||||||
} catch {
|
|
||||||
submitButton.status = 'error';
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
function simulateNetworkRequest() {
|
|
||||||
return new Promise(resolve => setTimeout(resolve, 2000));
|
|
||||||
}
|
|
||||||
|
|
||||||
submitButton.addEventListener('clicked', handleFormSubmission);
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Modal Component: `DeesModal`
|
## Components Overview
|
||||||
|
|
||||||
The `DeesModal` component is used to display content in an overlay. It is suitable for scenarios like alerts, dialog boxes, or interactive user forms. The modal can be highly customized with different header, content, and footer components.
|
Below is a comprehensive list of all available components:
|
||||||
|
|
||||||
#### Example Usage
|
| Category | Components |
|
||||||
|
|----------|------------|
|
||||||
|
| Core UI | `DeesButton`, `DeesBadge`, `DeesChips`, `DeesIcon`, `DeesLabel`, `DeesSpinner`, `DeesToast` |
|
||||||
|
| Forms | `DeesForm`, `DeesInputText`, `DeesInputCheckbox`, `DeesInputDropdown`, `DeesInputRadio`, `DeesInputFileupload`, `DeesInputIban`, `DeesInputPhone`, `DeesInputQuantitySelector`, `DeesInputMultitoggle`, `DeesFormSubmit` |
|
||||||
|
| Layout | `DeesAppuiBase`, `DeesAppuiMainmenu`, `DeesAppuiMainselector`, `DeesAppuiMaincontent`, `DeesAppuiAppbar`, `DeesMobileNavigation` |
|
||||||
|
| Data Display | `DeesTable`, `DeesDataviewCodebox`, `DeesDataviewStatusobject`, `DeesPdf` |
|
||||||
|
| Visualization | `DeesChartArea`, `DeesChartLog` |
|
||||||
|
| Dialogs & Overlays | `DeesModal`, `DeesContextmenu`, `DeesSpeechbubble`, `DeesWindowlayer` |
|
||||||
|
| Navigation | `DeesStepper`, `DeesProgressbar` |
|
||||||
|
| Development | `DeesEditor`, `DeesEditorMarkdown`, `DeesTerminal`, `DeesUpdater` |
|
||||||
|
|
||||||
|
## Detailed Component Documentation
|
||||||
|
|
||||||
|
### Core UI Components
|
||||||
|
|
||||||
|
#### `DeesButton`
|
||||||
|
A versatile button component supporting multiple styles and states.
|
||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
import { DeesModal } from '@design.estate/dees-catalog';
|
const button = document.createElement('dees-button');
|
||||||
import { html } from '@design.estate/dees-element';
|
button.text = 'Click me';
|
||||||
|
button.type = 'highlighted'; // Options: normal, highlighted, discreet
|
||||||
|
button.status = 'pending'; // Options: normal, pending, success, error
|
||||||
|
```
|
||||||
|
|
||||||
// Creating a modal
|
#### `DeesBadge`
|
||||||
const modalContent = html`<p>Welcome to our platform</p>`;
|
Display status indicators or counts with customizable styles.
|
||||||
const modal = DeesModal.createAndShow({
|
|
||||||
heading: 'Welcome',
|
```typescript
|
||||||
content: modalContent,
|
<dees-badge
|
||||||
|
type="success" // Options: default, primary, success, warning, error
|
||||||
|
text="New"
|
||||||
|
rounded
|
||||||
|
></dees-badge>
|
||||||
|
```
|
||||||
|
|
||||||
|
#### `DeesChips`
|
||||||
|
Interactive chips/tags with selection capabilities.
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
<dees-chips
|
||||||
|
selectionMode="multiple" // Options: none, single, multiple
|
||||||
|
chipsAreRemovable
|
||||||
|
.selectableChips=${[
|
||||||
|
{ key: 'tag1', value: 'Important' },
|
||||||
|
{ key: 'tag2', value: 'Urgent' }
|
||||||
|
]}
|
||||||
|
></dees-chips>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Form Components
|
||||||
|
|
||||||
|
#### `DeesForm`
|
||||||
|
Container component for form elements with built-in validation and data collection.
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
<dees-form>
|
||||||
|
<dees-input-text required label="Username"></dees-input-text>
|
||||||
|
<dees-input-password label="Password"></dees-input-password>
|
||||||
|
<dees-form-submit>Submit</dees-form-submit>
|
||||||
|
</dees-form>
|
||||||
|
```
|
||||||
|
|
||||||
|
#### `DeesInputText`
|
||||||
|
Text input field with validation and formatting options.
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
<dees-input-text
|
||||||
|
label="Email"
|
||||||
|
required
|
||||||
|
type="email"
|
||||||
|
placeholder="Enter your email"
|
||||||
|
></dees-input-text>
|
||||||
|
```
|
||||||
|
|
||||||
|
#### `DeesInputDropdown`
|
||||||
|
Dropdown selection component with search and multi-select capabilities.
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
<dees-input-dropdown
|
||||||
|
label="Country"
|
||||||
|
.options=${[
|
||||||
|
{ key: 'us', option: 'United States' },
|
||||||
|
{ key: 'uk', option: 'United Kingdom' }
|
||||||
|
]}
|
||||||
|
></dees-input-dropdown>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Layout Components
|
||||||
|
|
||||||
|
#### `DeesAppuiBase`
|
||||||
|
Base layout component for application structure.
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
<dees-appui-base>
|
||||||
|
<dees-appui-mainmenu></dees-appui-mainmenu>
|
||||||
|
<dees-appui-maincontent></dees-appui-maincontent>
|
||||||
|
</dees-appui-base>
|
||||||
|
```
|
||||||
|
|
||||||
|
#### `DeesAppuiMainmenu`
|
||||||
|
Navigation menu component for application sidebar.
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
<dees-appui-mainmenu
|
||||||
|
.menuItems=${[
|
||||||
|
{ label: 'Dashboard', icon: 'home' },
|
||||||
|
{ label: 'Settings', icon: 'cog' }
|
||||||
|
]}
|
||||||
|
></dees-appui-mainmenu>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Data Display Components
|
||||||
|
|
||||||
|
#### `DeesTable`
|
||||||
|
Advanced table component with sorting, filtering, and row selection.
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
<dees-table
|
||||||
|
.data=${tableData}
|
||||||
|
.columns=${[
|
||||||
|
{ key: 'name', label: 'Name' },
|
||||||
|
{ key: 'age', label: 'Age' }
|
||||||
|
]}
|
||||||
|
selectable
|
||||||
|
></dees-table>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Visualization Components
|
||||||
|
|
||||||
|
#### `DeesChartArea`
|
||||||
|
Area chart component using ApexCharts.
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
<dees-chart-area
|
||||||
|
.series=${[
|
||||||
|
{ name: 'Sales', data: [30, 40, 35, 50] }
|
||||||
|
]}
|
||||||
|
></dees-chart-area>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Dialog Components
|
||||||
|
|
||||||
|
#### `DeesModal`
|
||||||
|
Modal dialog component with customizable content and actions.
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
DeesModal.createAndShow({
|
||||||
|
heading: 'Confirm Action',
|
||||||
|
content: html`<p>Are you sure?</p>`,
|
||||||
menuOptions: [
|
menuOptions: [
|
||||||
{ name: 'Close', action: () => modal.destroy() },
|
{ name: 'Cancel', action: () => modal.destroy() },
|
||||||
{ name: 'Proceed', action: () => console.log('Proceeding') }
|
{ name: 'Confirm', action: () => handleConfirm() }
|
||||||
]
|
]
|
||||||
});
|
});
|
||||||
```
|
```
|
||||||
|
|
||||||
### Form Handling With `DeesForm`
|
### Development Components
|
||||||
|
|
||||||
The `DeesForm` and its related input elements simplify form creation and handling. The form component integrates validation, submission, and data collection functions.
|
#### `DeesEditor`
|
||||||
|
Code editor component based on Monaco Editor.
|
||||||
#### Creating a Form
|
|
||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
import {
|
<dees-editor
|
||||||
DeesForm,
|
language="typescript"
|
||||||
DeesInputText,
|
.value=${codeString}
|
||||||
DeesFormSubmit,
|
@change=${handleChange}
|
||||||
DeesInputDropdown
|
></dees-editor>
|
||||||
} from '@design.estate/dees-catalog';
|
|
||||||
|
|
||||||
const registrationForm = document.createElement('dees-form');
|
|
||||||
|
|
||||||
const nameInput = document.createElement('dees-input-text');
|
|
||||||
nameInput.label = 'Name';
|
|
||||||
nameInput.required = true;
|
|
||||||
|
|
||||||
const roleSelect = document.createElement('dees-input-dropdown');
|
|
||||||
roleSelect.label = 'Role';
|
|
||||||
roleSelect.options = [
|
|
||||||
{ option: 'Admin', key: 'admin' },
|
|
||||||
{ option: 'Editor', key: 'editor' }
|
|
||||||
];
|
|
||||||
|
|
||||||
const submitButton = document.createElement('dees-form-submit');
|
|
||||||
submitButton.text = 'Register';
|
|
||||||
|
|
||||||
registrationForm.appendChild(nameInput);
|
|
||||||
registrationForm.appendChild(roleSelect);
|
|
||||||
registrationForm.appendChild(submitButton);
|
|
||||||
|
|
||||||
registrationForm.addEventListener('formData', event => {
|
|
||||||
console.log('Form Data:', event.detail.data);
|
|
||||||
});
|
|
||||||
|
|
||||||
document.body.appendChild(registrationForm);
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Data Presentation with `DeesTable`
|
## Customization and Theming
|
||||||
|
|
||||||
The `DeesTable` component allows for effective data management and presentation through dynamic tables. It supports features such as sorting, selecting, and action-triggering from table items.
|
Components can be customized using CSS custom properties and the built-in theme system. Example:
|
||||||
|
|
||||||
#### Displaying a Data Table
|
```css
|
||||||
|
dees-button {
|
||||||
```typescript
|
--dees-button-background: #007bff;
|
||||||
import { DeesTable } from '@design.estate/dees-catalog';
|
--dees-button-color: white;
|
||||||
|
}
|
||||||
const data = [
|
|
||||||
{ name: 'Alice', status: 'Active' },
|
|
||||||
{ name: 'Bob', status: 'Inactive' }
|
|
||||||
];
|
|
||||||
|
|
||||||
const table = new DeesTable();
|
|
||||||
table.heading1 = 'User Table';
|
|
||||||
table.data = data;
|
|
||||||
|
|
||||||
document.body.appendChild(table);
|
|
||||||
|
|
||||||
// Custom Actions and Row Selection
|
|
||||||
table.addEventListener('rowSelected', (event) => console.log(event.detail));
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Structural Components
|
## Browser Support
|
||||||
|
|
||||||
`DeesAppuiBase`, along with components such as `DeesAppuiMainmenu` and `DeesAppuiMainselector`, provide the scaffolding needed for application UIs, particularly dashboards.
|
The library supports modern browsers with Web Components implementation:
|
||||||
|
- Chrome (latest)
|
||||||
|
- Firefox (latest)
|
||||||
|
- Safari (latest)
|
||||||
|
- Edge (latest)
|
||||||
|
|
||||||
#### Setting Up an Application Layout
|
## Contributing
|
||||||
|
|
||||||
```typescript
|
Please read our [Contributing Guidelines](CONTRIBUTING.md) for details on submitting pull requests.
|
||||||
import { DeesAppuiBase } from '@design.estate/dees-catalog';
|
|
||||||
|
|
||||||
const appBase = document.createElement('dees-appui-base');
|
|
||||||
document.body.appendChild(appBase);
|
|
||||||
```
|
|
||||||
|
|
||||||
### Data Visualization with ApexCharts
|
|
||||||
|
|
||||||
`DeesChartArea` provides easy integration with ApexCharts for creating detailed visualizations.
|
|
||||||
|
|
||||||
#### Implementing a Chart
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
import { DeesChartArea } from '@design.estate/dees-catalog';
|
|
||||||
|
|
||||||
// Create and configure a chart
|
|
||||||
const chart = new DeesChartArea();
|
|
||||||
document.body.appendChild(chart);
|
|
||||||
|
|
||||||
chart.chart.updateSeries([
|
|
||||||
{ name: 'Sales', data: [20, 40, 30, 50] }
|
|
||||||
]);
|
|
||||||
```
|
|
||||||
|
|
||||||
### Customization and Extensibility
|
|
||||||
|
|
||||||
The `@design.estate/dees-catalog` is built for extensibility and customization. You can extend components, integrate custom events, and style them as per your requirements. This ensures that your application remains unique and tailored to your audience.
|
|
||||||
|
|
||||||
The library not only saves development time by providing ready-made components but also enhances maintainability through its clean interfaces and TypeScript support, making your code robust and type-safe. With the library's expansive set of features, building modern web applications has never been easier. Enjoy the blend of simplicity and power that `@design.estate/dees-catalog` brings to the table.
|
|
||||||
|
|
||||||
## License and Legal Information
|
## License and Legal Information
|
||||||
|
|
||||||
|
|||||||
@ -3,6 +3,6 @@
|
|||||||
*/
|
*/
|
||||||
export const commitinfo = {
|
export const commitinfo = {
|
||||||
name: '@design.estate/dees-catalog',
|
name: '@design.estate/dees-catalog',
|
||||||
version: '1.5.0',
|
version: '1.5.1',
|
||||||
description: 'A comprehensive library that provides dynamic web components for building sophisticated and modern web applications using JavaScript and TypeScript.'
|
description: 'A comprehensive library that provides dynamic web components for building sophisticated and modern web applications using JavaScript and TypeScript.'
|
||||||
}
|
}
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user