@nexdom/uimed-vue 2.0.0-beta.8 → 2.0.0

package/skills/uimed-vue/references/api/components/text-field.md

@@ -0,0 +1,42 @@
+# UTextField
+
+Componente para utilização de campos de text.
+
+## Props
+
+| Prop          | Tipo                                                               | Padrão      | Descrição                                                                                                                                            |
+| ------------- | ------------------------------------------------------------------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `modelValue`  | `string`                                                           | `""`        | Valor digitado no campo.                                                                                                                             |
+| `variant`     | `"primary" \| "secondary"`                                         | `"primary"` | Aplica uma variação de estilo distinta ao campo.                                                                                                     |
+| `type`        | `"text" \| "phone" \| "email" \| "url" \| "password" \| "search" ` | `"text"`    | Ajusta o tipo de campo de texto. Com `password`, exibe o ícone "Mostrar senha", que alterna entre mostrar e ocultar o valor.                         |
+| `label`       | `string`                                                           |             | Título dado ao campo.                                                                                                                                |
+| `placeholder` | `string`                                                           |             | Exemplo de valor para preenchimento do campo.                                                                                                        |
+| `hint`        | `string`                                                           |             | Dica, instrução ou mensagem relacionada ao campo.                                                                                                    |
+| `required`    | `boolean`                                                          | `false`     | Torna o campo obrigatório para a submissão do formulário.                                                                                            |
+| `disabled`    | `boolean`                                                          | `false`     | Remove a possibilidade de interação com o campo.                                                                                                     |
+| `readonly`    | `boolean`                                                          | `false`     | Remove a possibilidade de edição do campo.                                                                                                           |
+| `loading`     | `boolean`                                                          | `false`     | Exibe um indicador de carregamento. O campo mantém o rótulo como nome acessível e fica marcado como ocupado, e leitores de tela ignoram o indicador. |
+| `clearable`   | `boolean`                                                          | `false`     | Exibe recurso para limpar o campo. O valor padrão muda para `true` quando o `type` é `search`.                                                       |
+| `dataTestid`  | `string`                                                           |             | Aplica atributo `data-testid` para testes sobre o componente.                                                                                        |
+
+## Eventos
+
+| Event               | Retorno  | Descrição                                                          |
+| ------------------- | -------- | ------------------------------------------------------------------ |
+| `update:modelValue` | `string` | Retorna o novo valor do campo sempre que o usuário altera o mesmo. |
+
+## Exemplo
+
+```vue
+<template>
+  <u-text-field v-model="name" label="Nome" />
+  Olá, {{ name }}!
+</template>
+
+<script lang="ts" setup>
+import { ref } from "vue";
+import { UTextField } from "@nexdom/uimed-vue/components";
+
+const name = ref("");
+</script>
+```

package/skills/uimed-vue/references/api/composables/use-confirm.md

@@ -0,0 +1,96 @@
+# useConfirm
+
+Composable para execução de ações somente após a confirmação do usuário em um diálogo.
+
+## Tipo
+
+```ts
+type ColorVariant = "primary" | "secondary" | "positive" | "informative" | "caution" | "danger";
+
+interface ConfirmOptions {
+  title?: string;
+  message: string;
+  confirmText?: string;
+  cancelText?: string;
+  color?: ColorVariant;
+}
+
+function useConfirm(): {
+  confirm: <F extends (...args: Parameters<F>) => PromiseLike<Awaited<ReturnType<F>>>>(
+    options: ConfirmOptions,
+    action: F,
+    ...params: Parameters<F>
+  ) => Promise<Awaited<ReturnType<F>> | false>;
+  isRunning: import("vue").ComputedRef<boolean>;
+};
+```
+
+## Detalhes
+
+Retorna uma função (`confirm`) e uma [`computed`](https://vuejs.org/guide/essentials/computed.html) (`isRunning`) para monitorar a execução da ação. Cada chamada de `useConfirm` tem o seu próprio `isRunning`.
+
+A função (`confirm`) apresenta um diálogo com os botões "Cancelar" e "Confirmar". A ação (`action`) é obrigatória e só é executada, com os parâmetros seguintes (`params`), depois que o usuário clica em "Confirmar". Enquanto ela executa:
+
+- o botão de confirmação apresenta um indicador de carregamento;
+- o botão de cancelamento fica desabilitado;
+- o diálogo não pode ser fechado;
+- `isRunning` é `true`.
+
+Ao terminar a execução, o diálogo fecha. Se houver qualquer erro durante a execução, a mensagem do erro é apresentada em um [`toast`](./use-toast.md), assim como no [`useRunOrToast`](./use-run-or-toast.md).
+
+Os diálogos de `confirm` compartilham a fila de diálogos do [`useDialog`](./use-dialog.md).
+
+### `ConfirmOptions`
+
+| Opção         | Tipo                                                                                         | Padrão        | Descrição                                                        |
+| ------------- | -------------------------------------------------------------------------------------------- | ------------- | ---------------------------------------------------------------- |
+| `title`       | `string`                                                                                     |               | Título do diálogo, em texto simples (HTML não é interpretado).   |
+| `message`     | `string`                                                                                     |               | Mensagem do diálogo, em texto simples (HTML não é interpretado). |
+| `confirmText` | `string`                                                                                     | `"Confirmar"` | Texto do botão de confirmação.                                   |
+| `cancelText`  | `string`                                                                                     | `"Cancelar"`  | Texto do botão de cancelamento.                                  |
+| `color`       | `"primary"` \| `"secondary"` \| `"positive"` \| `"informative"` \| `"caution"` \| `"danger"` | `"primary"`   | Cor do botão de confirmação.                                     |
+
+### Retorno
+
+`confirm` resolve o retorno da ação, ou `false` quando:
+
+- a ação falha;
+- o usuário clica no botão de cancelamento;
+- o usuário pressiona a tecla `Esc` ou clica fora do diálogo;
+- o usuário usa o botão "voltar" do navegador, em aplicações que usam o [Vue Router](https://router.vuejs.org/), exceto quando ele leva a uma página aberta com `router.replace` (como a página pela qual o usuário entrou na aplicação).
+
+### Acessibilidade
+
+O diálogo usa o papel `alertdialog`. O foco inicia no botão de cancelamento, fica restrito ao diálogo enquanto ele estiver aberto e volta ao elemento de origem quando ele fecha.
+
+## Exemplo
+
+```vue
+<template>
+  <u-main>
+    <!-- ... -->
+  </u-main>
+</template>
+<script lang="ts" setup>
+import { UMain } from "@nexdom/uimed-vue/components";
+import { useConfirm } from "@nexdom/uimed-vue/composables";
+
+const { confirm, isRunning } = useConfirm();
+
+const removed = await confirm(
+  {
+    title: "Excluir paciente",
+    message: "Esta ação não pode ser desfeita.",
+    confirmText: "Excluir",
+    color: "danger",
+  },
+  () => api.deletePatient(id),
+);
+
+if (removed === false) {
+  // Executa algo quando o usuário cancela ou a ação falha.
+} else {
+  // Executa algo quando a ação executa com sucesso.
+}
+</script>
+```

package/skills/uimed-vue/references/api/composables/use-dialog.md

@@ -0,0 +1,95 @@
+# useDialog
+
+Composable para apresentação de diálogos.
+
+## Tipo
+
+```ts
+type ButtonVariant = "primary" | "secondary" | "ghost";
+
+type ColorVariant = "primary" | "secondary" | "positive" | "informative" | "caution" | "danger";
+
+interface DialogAction<T extends string = string> {
+  text: string;
+  value: T;
+  variant?: ButtonVariant;
+  color?: ColorVariant;
+}
+
+interface DialogOptions<T extends string = string> {
+  title?: string;
+  message: string;
+  actions?: DialogAction<T>[];
+}
+
+function dialog<T extends string = never>(options: DialogOptions<T>): Promise<T | undefined>;
+
+function useDialog(): {
+  dialog: typeof dialog;
+};
+```
+
+## Detalhes
+
+Retorna uma função (`dialog`) para exibir diálogos. Ela devolve uma `Promise` que resolve quando o diálogo é fechado.
+
+Os diálogos são apresentados um de cada vez, na ordem em que foram solicitados, incluindo os de [`useConfirm`](./use-confirm.md). Diálogos solicitados enquanto nenhum [`UMain`](../components/main.md) estiver montado aguardam até que um seja montado. Havendo mais de um `UMain` na página, apenas o primeiro montado apresenta os diálogos.
+
+### `DialogOptions`
+
+| Opção     | Tipo                              | Padrão                 | Descrição                                                                   |
+| --------- | --------------------------------- | ---------------------- | --------------------------------------------------------------------------- |
+| `title`   | `string`                          |                        | Título do diálogo, em texto simples (HTML não é interpretado).              |
+| `message` | `string`                          |                        | Mensagem do diálogo, em texto simples (HTML não é interpretado).            |
+| `actions` | [`DialogAction[]`](#dialogaction) | `[{ text: "Fechar" }]` | Botões apresentados no rodapé do diálogo, alinhados à direita, nesta ordem. |
+
+### `DialogAction`
+
+| Opção     | Tipo                                                                                         | Padrão                                       | Descrição                                              |
+| --------- | -------------------------------------------------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------ |
+| `text`    | `string`                                                                                     |                                              | Texto do botão.                                        |
+| `value`   | `string`                                                                                     |                                              | Valor devolvido por `dialog` quando o botão é clicado. |
+| `variant` | `"primary"` \| `"secondary"` \| `"ghost"`                                                    | `"ghost"`, ou `"primary"` para a última ação | Variante do botão.                                     |
+| `color`   | `"primary"` \| `"secondary"` \| `"positive"` \| `"informative"` \| `"caution"` \| `"danger"` | `"primary"`                                  | Cor do botão.                                          |
+
+### Retorno
+
+`dialog` resolve o `value` da ação clicada, ou `undefined` quando o diálogo é fechado:
+
+- pelo botão padrão "Fechar";
+- pela tecla `Esc`;
+- por um clique fora do diálogo;
+- pelo botão "voltar" do navegador, em aplicações que usam o [Vue Router](https://router.vuejs.org/), exceto quando ele leva a uma página aberta com `router.replace` (como a página pela qual o usuário entrou na aplicação).
+
+### Acessibilidade
+
+O foco inicia na primeira ação, fica restrito ao diálogo enquanto ele estiver aberto e volta ao elemento de origem quando ele fecha. O diálogo é identificado pelo título (ou pela mensagem, quando não houver título) e descrito pela mensagem.
+
+## Exemplo
+
+```vue
+<template>
+  <u-main>
+    <!-- ... -->
+  </u-main>
+</template>
+<script lang="ts" setup>
+import { UMain } from "@nexdom/uimed-vue/components";
+import { useDialog } from "@nexdom/uimed-vue/composables";
+
+const { dialog } = useDialog();
+
+const answer = await dialog({
+  title: "Sessão expirando",
+  message: "Deseja continuar conectado?",
+  actions: [
+    { text: "Sair", value: "sair" },
+    { text: "Continuar conectado", value: "continuar" },
+  ],
+});
+
+if (answer === "sair") {
+  // Executa algo quando o usuário escolhe sair.
+}
+</script>
+```

package/skills/uimed-vue/references/api/composables/use-run-or-toast.md

@@ -0,0 +1,58 @@
+# useRunOrToast
+
+Composable para execução de métodos assíncronos e apresentação de mensagens, tipo _toast_, em caso de falha.
+
+## Tipo
+
+```ts
+function useRunOrToast(): {
+  run: <T extends (...args: Parameters<T>) => PromiseLike<Awaited<ReturnType<T>>>>(
+    toRun: T,
+    ...params: Parameters<T>
+  ) => Promise<Awaited<ReturnType<T>> | false>;
+  isRunning: import("vue").ComputedRef<boolean>;
+};
+```
+
+## Detalhes
+
+Retorna uma função (`run`) e uma [`computed`](https://vuejs.org/guide/essentials/computed.html) (`isRunning`) para monitorar a execução da função.
+
+A função (`run`) espera receber um parâmetro com a função que deverá ser executada (`callback`), então devolverá o retorno dessa função.
+
+Se houver qualquer erro durante a execução da função (`run`), a mesma irá chamar o [`toast`](./use-toast.md) e apresentar o erro, retornando `false` em seguida.
+
+## Exemplo
+
+```vue
+<template>
+  <u-main>
+    <!-- ... -->
+  </u-main>
+</template>
+<script lang="ts" setup>
+import { UMain } from "@nexdom/uimed-vue/components";
+import { useRunOrToast } from "@nexdom/uimed-vue/composables";
+
+const { run, isRunning } = useRunOrToast();
+
+// Apresenta: false
+console.log(isRunning.value);
+
+const promise = run(() => someFunction(param1, param2));
+
+// Apresenta: true
+console.log(isRunning.value);
+
+const response = await promise;
+
+// Apresenta: false
+console.log(isRunning.value);
+
+if (response === false) {
+  // Executa algo em caso de falha no método.
+} else {
+  // Executa algo quando o método executa com sucesso.
+}
+</script>
+```

package/skills/uimed-vue/references/api/composables/use-toast.md

@@ -0,0 +1,48 @@
+# useToast
+
+Composable para apresentação de mensagens tipo _toast_.
+
+## Tipo
+
+```ts
+type FeedbackColorVariant = "positive" | "informative" | "caution" | "danger";
+
+interface ToastOptions {
+  message: string;
+  color?: FeedbackColorVariant;
+}
+
+function toast(options: ToastOptions): void;
+
+function useToast(): {
+  toast: typeof toast;
+};
+```
+
+## Detalhes
+
+Retorna uma função (`toast`) para exibir novas mensagens _toast_. As mensagens são apresentadas pelo [`UMain`](../components/main.md), que precisa estar montado na página.
+
+### `ToastOptions`
+
+| Opção     | Tipo                                                         | Padrão          | Descrição                   |
+| --------- | ------------------------------------------------------------ | --------------- | --------------------------- |
+| `message` | `string`                                                     |                 | Texto apresentado no toast. |
+| `color`   | `"positive"` \| `"informative"` \| `"caution"` \| `"danger"` | `"informative"` | Cor do toast.               |
+
+## Exemplo
+
+```vue
+<template>
+  <u-main>
+    <!-- ... -->
+  </u-main>
+</template>
+<script lang="ts" setup>
+import { UMain } from "@nexdom/uimed-vue/components";
+import { useToast } from "@nexdom/uimed-vue/composables";
+
+const { toast } = useToast();
+toast({ message: "Olá, Toast!" });
+</script>
+```

package/skills/uimed-vue/references/api/composables/use-unsaved-changes.md

@@ -0,0 +1,106 @@
+# useUnsavedChanges
+
+Composable para evitar a perda de alterações não salvas de um formulário ao sair da página.
+
+## Tipo
+
+```ts
+type ColorVariant = "primary" | "secondary" | "positive" | "informative" | "caution" | "danger";
+
+interface UnsavedChangesValues<T> {
+  previous: import("vue").MaybeRefOrGetter<T>;
+  current: import("vue").MaybeRefOrGetter<T>;
+}
+
+interface UnsavedChangesOptions {
+  title?: string;
+  message?: string;
+  confirmText?: string;
+  cancelText?: string;
+  color?: ColorVariant;
+  beforeUnload?: boolean;
+}
+
+function useUnsavedChanges<T>(
+  values: UnsavedChangesValues<T>,
+  options?: UnsavedChangesOptions,
+): {
+  hasChanges: import("vue").ComputedRef<boolean>;
+};
+```
+
+## Detalhes
+
+Deve ser chamada no `setup` de um componente. Retorna uma [`computed`](https://vuejs.org/guide/essentials/computed.html) somente leitura (`hasChanges`), que é `true` enquanto o valor original (`previous`) e o valor atual (`current`) forem diferentes.
+
+`previous` e `current` aceitam uma `ref`, um getter ou um objeto `reactive`, e são comparados em profundidade:
+
+- a ordem das propriedades não importa;
+- uma propriedade com `undefined` é igual a uma propriedade ausente;
+- datas (`Date`) são comparadas pelo horário;
+- listas são comparadas item a item, na mesma ordem;
+- objetos simples (literais ou sem protótipo) são comparados propriedade a propriedade;
+- os demais objetos, como `File`, `Blob`, `Map`, `Set` e instâncias de classes, são comparados por referência;
+- os demais valores são comparados com [`Object.is`](https://developer.mozilla.org/pt-BR/docs/Web/JavaScript/Reference/Global_Objects/Object/is), então `null`, `""` e `undefined` são diferentes entre si e `NaN` é igual a `NaN`.
+
+Para marcar o formulário como salvo, atribua a `previous` uma cópia do valor atual. Se `previous` e `current` apontarem para o mesmo objeto, `hasChanges` fica sempre `false`.
+
+### Navegação
+
+Quando o componente é renderizado por um `<RouterView>` do [Vue Router](https://router.vuejs.org/) (diretamente ou dentro de uma página), sair da página com alterações apresenta um diálogo de [confirmação](./use-confirm.md):
+
+- "Sair sem salvar" continua a navegação;
+- "Continuar editando", a tecla `Esc` ou um clique fora do diálogo cancelam a navegação.
+
+`hasChanges` é lido no momento da navegação, então uma navegação feita logo depois de atualizar `previous` acontece sem diálogo. Enquanto o diálogo estiver aberto, novas navegações reaproveitam a mesma resposta, que vale para a navegação mais recente. Em aplicações com Vue Router e histórico do navegador (`createWebHistory` ou `createWebHashHistory`), o botão "voltar" do navegador passa pela mesma verificação e, com o diálogo aberto, não o fecha (ao contrário do [`useConfirm`](./use-confirm.md)): a resposta passa a valer para o "voltar". Cada chamada de `useUnsavedChanges` com alterações apresenta o seu diálogo.
+
+A verificação é removida quando o componente é desmontado. Ela não acontece:
+
+- fora de um `<RouterView>` ou em aplicações sem Vue Router;
+- em mudanças apenas nos parâmetros (`params`) ou na consulta (`query`) da mesma rota.
+
+O diálogo depende do [`UMain`](../components/main.md): sem ele, o diálogo não aparece e a navegação fica pendente.
+
+### Aviso do navegador
+
+Com `beforeUnload` ligado (padrão), recarregar a página, fechar a aba ou sair da aplicação por um link externo com alterações apresenta o aviso do próprio navegador. O texto é definido pelo navegador, e o aviso só aparece se o usuário já interagiu com a página. O aviso só é registrado enquanto houver alterações e é removido quando o componente é desmontado ou, dentro de um `<KeepAlive>`, desativado. Alterações feitas enquanto o componente está desativado (por exemplo, por uma requisição que termina depois que o usuário saiu da página) só registram o aviso quando ele é ativado de novo.
+
+### `UnsavedChangesOptions`
+
+| Opção          | Tipo                                                                                         | Padrão                                                                     | Descrição                                                                               |
+| -------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| `title`        | `string`                                                                                     | `"Alterações não salvas"`                                                  | Título do diálogo, em texto simples (HTML não é interpretado).                          |
+| `message`      | `string`                                                                                     | `"Existem alterações que ainda não foram salvas. Deseja sair sem salvar?"` | Mensagem do diálogo, em texto simples (HTML não é interpretado).                        |
+| `confirmText`  | `string`                                                                                     | `"Sair sem salvar"`                                                        | Texto do botão que continua a navegação.                                                |
+| `cancelText`   | `string`                                                                                     | `"Continuar editando"`                                                     | Texto do botão que cancela a navegação.                                                 |
+| `color`        | `"primary"` \| `"secondary"` \| `"positive"` \| `"informative"` \| `"caution"` \| `"danger"` | `"danger"`                                                                 | Cor do botão que continua a navegação.                                                  |
+| `beforeUnload` | `boolean`                                                                                    | `true`                                                                     | Apresenta o aviso do navegador ao recarregar, fechar a aba ou sair por um link externo. |
+
+### Acessibilidade
+
+O diálogo usa o papel `alertdialog`. O foco inicia no botão "Continuar editando", fica restrito ao diálogo enquanto ele estiver aberto e volta ao elemento de origem quando ele fecha.
+
+## Exemplo
+
+```vue
+<template>
+  <u-text-field v-model="form.name" label="Nome" />
+  <u-button :disabled="!hasChanges" @click="save">Salvar</u-button>
+</template>
+<script lang="ts" setup>
+import { ref, toRaw } from "vue";
+import { UButton, UTextField } from "@nexdom/uimed-vue/components";
+import { useUnsavedChanges } from "@nexdom/uimed-vue/composables";
+
+const saved = ref({ name: "Maria" });
+const form = ref(structuredClone(toRaw(saved.value)));
+
+const { hasChanges } = useUnsavedChanges({ previous: saved, current: form });
+
+async function save() {
+  await api.save(form.value);
+  // Marca o formulário como salvo
+  saved.value = structuredClone(toRaw(form.value));
+}
+</script>
+```

package/skills/uimed-vue/references/api/index.md

@@ -0,0 +1 @@
+# APIs Disponíveis