Add readme
fandi.susanto.bts
1 month ago
parent
630e684132
commit
d2916b04f7
@ -1,54 +1,176 @@
|
|||||||
# concise-ui
|
# Concise UI
|
||||||
|
|
||||||
This template should help get you started developing with Vue 3 in Vite.
|
Concise UI is a Vue 3 component framework for desktop-first enterprise and productivity software.
|
||||||
|
|
||||||
## Recommended IDE Setup
|
It is designed for applications such as ERP, WMS, CRM, POS, finance, inventory, administration, and other internal business systems. The goal is a compact, professional interface that displays information efficiently without imitating Bootstrap, Material Design, or old desktop software.
|
||||||
|
|
||||||
[VS Code](https://code.visualstudio.com/) + [Vue (Official)](https://marketplace.visualstudio.com/items?itemName=Vue.volar) (and disable Vetur).
|
> Concise UI is currently under active development. Its public API may change before the first stable release.
|
||||||
|
|
||||||
## Recommended Browser Setup
|
## Design principles
|
||||||
|
|
||||||
- Chromium-based browsers (Chrome, Edge, Brave, etc.):
|
- High information density with compact controls and restrained spacing
|
||||||
- [Vue.js devtools](https://chromewebstore.google.com/detail/vuejs-devtools/nhdogjmejiglipccpnnnanhbledajbpd)
|
- Clear hierarchy through typography, borders, and layout
|
||||||
- [Turn on Custom Object Formatter in Chrome DevTools](http://bit.ly/object-formatters)
|
- Conservative use of color for actions, status, selection, and validation
|
||||||
- Firefox:
|
- Desktop-first mouse and keyboard interaction
|
||||||
- [Vue.js devtools](https://addons.mozilla.org/en-US/firefox/addon/vue-js-devtools/)
|
- Accessible native semantics where possiblehttps://git.icodeformoney.com/fandi/concise-uihttps://git.icodeformoney.com/fandi/concise-ui
|
||||||
- [Turn on Custom Object Formatter in Firefox DevTools](https://fxdx.dev/firefox-devtools-custom-object-formatters/)
|
- Lightweight components without unnecessary runtime dependencies
|
||||||
|
- Scoped SCSS and CSS variables for theme customization
|
||||||
|
- Predictable Vue APIs and public TypeScript types
|
||||||
|
|
||||||
## Type Support for `.vue` Imports in TS
|
The complete design direction is documented in [AGENTS.md](./AGENTS.md).
|
||||||
|
|
||||||
TypeScript cannot handle type information for `.vue` imports by default, so we replace the `tsc` CLI with `vue-tsc` for type checking. In editors, we need [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar) to make the TypeScript language service aware of `.vue` types.
|
## Components
|
||||||
|
|
||||||
## Customize configuration
|
### Navigation and layout
|
||||||
|
|
||||||
See [Vite Configuration Reference](https://vite.dev/config/).
|
- `CAppBar`
|
||||||
|
- `CMenu`
|
||||||
|
- `CSeparator`
|
||||||
|
- `CSideBar`
|
||||||
|
|
||||||
## Project Setup
|
### Actions and feedback
|
||||||
|
|
||||||
```sh
|
- `CButton`
|
||||||
npm install
|
- `CProgressBar`
|
||||||
|
|
||||||
|
### Form structure
|
||||||
|
|
||||||
|
- `CFormField`
|
||||||
|
- `CInputGroup`
|
||||||
|
- `CInputAddon`
|
||||||
|
|
||||||
|
### Inputs
|
||||||
|
|
||||||
|
- `CInput`
|
||||||
|
- `CTextArea`
|
||||||
|
- `CPassword`
|
||||||
|
- `CNumberInput`
|
||||||
|
|
||||||
|
### Selection controls
|
||||||
|
|
||||||
|
- `CCheckbox`
|
||||||
|
- `CRadio`
|
||||||
|
- `CSelect`
|
||||||
|
- `CMultiSelect`
|
||||||
|
- `CAutoComplete`
|
||||||
|
|
||||||
|
### Symbols
|
||||||
|
|
||||||
|
- `CIcon`
|
||||||
|
|
||||||
|
`CIcon` displays Unicode symbols and emoji supplied by the application. Concise UI does not bundle an icon font or emoji package.
|
||||||
|
|
||||||
|
## Basic usage
|
||||||
|
|
||||||
|
Components and their public types are exported from the package entry point:
|
||||||
|
|
||||||
|
```vue
|
||||||
|
<script setup lang="ts">
|
||||||
|
import { ref } from 'vue'
|
||||||
|
import { CButton, CFormField, CInput, CProgressBar } from '@icfm/concise-ui'
|
||||||
|
|
||||||
|
const name = ref('')
|
||||||
|
const progress = ref(35)
|
||||||
|
</script>
|
||||||
|
|
||||||
|
<template>
|
||||||
|
<CFormField label="Customer name" required>
|
||||||
|
<CInput v-model="name" placeholder="Enter a name" />
|
||||||
|
</CFormField>
|
||||||
|
|
||||||
|
<CButton variant="primary">Save</CButton>
|
||||||
|
<CProgressBar :value="progress" show-value />
|
||||||
|
</template>
|
||||||
```
|
```
|
||||||
|
|
||||||
### Compile and Hot-Reload for Development
|
Component styling is authored as scoped SCSS and uses theme variables. The production build emits `dist/concise-ui.css` alongside the JavaScript bundles; applications must include that generated stylesheet. Theme variables can customize presentation without changing component behavior.
|
||||||
|
|
||||||
```sh
|
## Data-driven selection
|
||||||
npm run dev
|
|
||||||
|
`CSelect` and `CMultiSelect` accept standard `{ label, value }` records or raw objects with accessor props:
|
||||||
|
|
||||||
|
```vue
|
||||||
|
<script setup lang="ts">
|
||||||
|
import { ref } from 'vue'
|
||||||
|
import { CSelect } from '@icfm/concise-ui'
|
||||||
|
|
||||||
|
const products = [
|
||||||
|
{ id: 1, name: 'Book', code: 'BOO' },
|
||||||
|
{ id: 2, name: 'Stove', code: 'STV' },
|
||||||
|
]
|
||||||
|
|
||||||
|
const selectedProduct = ref(null)
|
||||||
|
</script>
|
||||||
|
|
||||||
|
<template>
|
||||||
|
<CSelect
|
||||||
|
v-model="selectedProduct"
|
||||||
|
:options="products"
|
||||||
|
option-label="name"
|
||||||
|
option-key="id"
|
||||||
|
filterable
|
||||||
|
clearable
|
||||||
|
/>
|
||||||
|
</template>
|
||||||
```
|
```
|
||||||
|
|
||||||
### Type-Check, Compile and Minify for Production
|
Omitting `option-value` binds the complete object. Adding `option-value="id"` binds only the ID.
|
||||||
|
|
||||||
|
Filterable `CSelect` and `CAutoComplete` also support parent-controlled remote searching through `@search`, `debounce-wait`, `min-search-length`, and `loading`. Components coordinate the interaction but leave authentication, networking, cancellation, and error handling to the application.
|
||||||
|
|
||||||
|
## Documentation application
|
||||||
|
|
||||||
|
The repository contains a documentation application with live examples and highlighted Vue and JavaScript snippets for the public components.
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
npm run build
|
npm install
|
||||||
|
npm run dev
|
||||||
```
|
```
|
||||||
|
|
||||||
### Run Unit Tests with [Vitest](https://vitest.dev/)
|
Open the local URL printed by Vite and navigate to **Components**.
|
||||||
|
|
||||||
|
## Development commands
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
|
# Start the documentation development server
|
||||||
|
npm run dev
|
||||||
|
|
||||||
|
# Type-check, build the library, and emit declarations
|
||||||
|
npm run build
|
||||||
|
|
||||||
|
# Run unit tests
|
||||||
npm run test:unit
|
npm run test:unit
|
||||||
|
|
||||||
|
# Run the configured linters
|
||||||
|
npm run lint
|
||||||
|
|
||||||
|
# Format source files
|
||||||
|
npm run format
|
||||||
```
|
```
|
||||||
|
|
||||||
### Lint with [ESLint](https://eslint.org/)
|
The supported Node.js versions are `^22.18.0` or `>=24.12.0`. Vue `^3.5.0` is a peer dependency.
|
||||||
|
|
||||||
```sh
|
## Project structure
|
||||||
npm run lint
|
|
||||||
|
```text
|
||||||
|
src/
|
||||||
|
├─ components/ Public component implementations and types
|
||||||
|
├─ documentation/ Documentation-only components
|
||||||
|
├─ layouts/ Documentation application layouts
|
||||||
|
├─ pages/components/ Component guides and live examples
|
||||||
|
├─ router/ Documentation routes
|
||||||
|
├─ styles/ Documentation application styles
|
||||||
|
└─ index.ts Public library exports
|
||||||
```
|
```
|
||||||
|
|
||||||
|
## Adding a component
|
||||||
|
|
||||||
|
The required component workflow is documented in [AGENTS.md](./AGENTS.md#creating-a-new-component). In summary:
|
||||||
|
|
||||||
|
1. Define the API, states, events, slots, model shape, and keyboard behavior.
|
||||||
|
2. Implement the component and any reusable public types.
|
||||||
|
3. Include accessibility and theme-aware compact styling.
|
||||||
|
4. Export the component and its public types from `src/index.ts`.
|
||||||
|
5. Create its documentation page with live examples and code snippets.
|
||||||
|
6. Register its documentation route and both navigation entries.
|
||||||
|
7. Review API consistency, accessibility, documentation accuracy, and the final diff.
|
||||||
|
|||||||
Loading…
Reference in New Issue