https://github.com/da6-dev/fluidstate-ui
https://github.com/da6-dev/fluidstate-ui
Last synced: 4 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/da6-dev/fluidstate-ui
- Owner: Da6-Dev
- License: mit
- Created: 2025-09-11T11:05:08.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-09-11T12:04:07.000Z (10 months ago)
- Last Synced: 2025-09-11T14:02:50.586Z (10 months ago)
- Language: HTML
- Size: 17.6 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 📦 FluidState UI
### Gestão visual de estados para qualquer UI, sem frameworks.
Uma biblioteca JS + CSS para aplicar estados dinâmicos em botões, inputs, cards, modais e qualquer elemento HTML.
Rápida, leve e universal: funciona com HTML puro ou em frameworks (React, Vue, Angular, etc).
## ✨ Por que usar?
* **🚀 Plug & Play:** Use `data-state` ou classes sem precisar escrever lógica repetitiva.
* **🎨 Design tokens prontos:** Estilos e microinterações para os estados mais comuns (loading, success, error, warning, disabled).
* **⚡ API mínima em JS:** Altere estados em uma linha.
* **🧩 Independente de frameworks:** Funciona em qualquer projeto.
* **🛢 Extensível:** Crie seus próprios estados e temas.
## 📦 Instalação
Instale via NPM:
```bash
npm install fluidstate-ui
```
Ou adicione via CDN no seu HTML:
```html
```
## 🚀 Uso Básico
**1. Adicione o atributo `data-state` ao seu elemento HTML:**
```html
Salvar
```
**2. Controle o estado com JavaScript:**
```javascript
// Muda para "loading"
FluidState.set("#saveBtn", "loading");
// Depois de 2s, mostra sucesso
setTimeout(() => {
FluidState.set("#saveBtn", "success");
}, 2000);
```
**3. A biblioteca aplica o CSS correspondente automaticamente:**
```css
/* Estilos incluídos na biblioteca */
[data-state="idle"] {
background: #007bff;
color: white;
}
[data-state="loading"] {
background: #999;
pointer-events: none;
position: relative;
}
[data-state="loading"]::after {
content: "...";
animation: blink 1s infinite;
}
[data-state="success"] {
background: #28a745;
animation: pop 0.3s ease;
}
[data-state="error"] {
background: #dc3545;
animation: shake 0.3s ease;
}
```
## 🎨 Estados Disponíveis por Padrão
* `idle`: estado inicial.
* `loading`: desabilita interação e mostra um indicador.
* `success`: cor verde + animação de confirmação.
* `error`: cor vermelha + animação de "shake".
* `warning`: cor amarela + animação de "pulse".
* `disabled`: cor cinza, sem interação.
## ⚡ API
* **`FluidState.set(selector, state)`**: Define o estado de um ou mais elementos.
```javascript
FluidState.set("#saveBtn", "loading");
```
* **`FluidState.get(selector)`**: Obtém o estado atual de um elemento.
```javascript
const currentState = FluidState.get("#saveBtn"); // Retorna, por exemplo: "loading"
```
* **`FluidState.reset(selector)`**: Remove o estado, fazendo o elemento voltar ao seu estilo padrão ou ao estado `idle`.
```javascript
FluidState.reset("#saveBtn");
```
## 🧩 Customização
Você pode facilmente criar seus próprios estados. Basta definir o estilo no seu CSS e usar o nome do estado na API.
**CSS:**
```css
[data-state="pending"] {
background: orange;
color: white;
animation: pulse 1s infinite;
}
```
**JavaScript:**
```javascript
FluidState.set("#orderStatus", "pending");
```
## 🛠 Exemplo Prático: Formulário de Login
**HTML:**
```html
Entrar
```
**JavaScript:**
```javascript
document.querySelector("#loginForm").onsubmit = async (e) => {
e.preventDefault();
const loginBtn = "#loginBtn";
FluidState.set(loginBtn, "loading");
// Simula uma chamada de API
try {
const success = await fakeApiCall();
FluidState.set(loginBtn, "success");
} catch (error) {
FluidState.set(loginBtn, "error");
}
};
```
## 🌍 Casos de Uso
* Botões de login, cadastro e submissão de formulários.
* Checkouts de e-commerce com feedback instantâneo.
* Passos (steps) em processos de onboarding.
* Status de tarefas (upload, download, processamento).
* Componentes de dashboards e UIs administrativas.
## 📊 Diferenciais no Mercado
* **Não é apenas CSS, nem apenas JS**: é a ponte entre os dois, unindo estilo e lógica.
* **Reduz boilerplate**: elimina a necessidade de código repetitivo para gerenciar classes e estilos de estado.
* **Feedback universal**: fornece uma experiência de usuário consistente em qualquer stack tecnológica.
* **Compatível**: pode ser usado junto com bibliotecas utilitárias como Tailwind CSS sem conflitos.
## 🔮 Futuras Features
* Temas prontos (dark, neon, minimal).
* Animações configuráveis via API.
* Integração com atributos ARIA para acessibilidade automática.
* Compatibilidade nativa com Web Components.
## 📜 Licença
Este projeto está licenciado sob a Licença MIT. Veja o arquivo [LICENSE.md](LICENSE.md) para mais detalhes.