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

package/skills/uimed-vue/references/guide/components/dialog.md

@@ -0,0 +1,269 @@
+# Janelas modais
+
+O componente para apresentar conteúdo em uma janela modal, sobre a página, se chama `Dialog`. Enquanto a janela está aberta, o restante da página fica inacessível.
+
+> [!Warning]
+> Deve ser utilizado no lugar do `<dialog>` nativo.
+
+A janela abre e fecha pelo `v-model`. Para apresentar apenas uma mensagem ou pedir uma confirmação, prefira as composables [useDialog](../composables/use-dialog.md) e [useConfirm](../composables/use-confirm.md).
+
+## Uso
+
+A prop `title` define o título da janela, em texto simples e em uma única linha (títulos longos são cortados com reticências), e o conteúdo vai no slot padrão. A prop `actions` define os botões exibidos no rodapé, alinhados à direita, nesta ordem. Coloque a ação principal por último.
+
+Clicar em uma ação **não fecha** a janela: feche-a no `onClick`, alterando o `v-model` para `false`.
+
+```vue
+<template>
+  <u-button @click="open = true">Ver detalhes</u-button>
+  <u-dialog v-model="open" title="Consulta agendada" :actions>
+    A consulta de Maria da Silva foi agendada para 12/10, às 14h, com a Dra. Ana Souza.
+  </u-dialog>
+</template>
+
+<script lang="ts" setup>
+import { ref } from "vue";
+import type { ComponentProps } from "vue-component-type-helpers";
+import { UButton, UDialog } from "@nexdom/uimed-vue/components";
+
+type DialogAction = NonNullable<ComponentProps<typeof UDialog>["actions"]>[number];
+
+const open = ref(false);
+
+const actions: DialogAction[] = [{ label: "Fechar", onClick: () => (open.value = false) }];
+</script>
+```
+
+### Fechando a janela
+
+Além das ações, o usuário pode fechar a janela pela tecla `Esc` ou clicando fora dela.
+
+O botão "voltar" do navegador também fecha a janela, sem sair da página, em aplicações que usam o [Vue Router](https://router.vuejs.org/). A exceção é quando o "voltar" leva a uma página aberta com `router.replace`, como a página pela qual o usuário entrou na aplicação: nesse caso, a navegação acontece e a janela continua aberta.
+
+Quando o usuário fecha a janela por um desses meios, ela começa a sumir na hora, mas o `v-model` só passa a ser `false` ao fim da animação de fechamento. Por isso:
+
+- atribuir `true` ao `v-model` durante essa animação não tem efeito, porque ele ainda é `true`: a janela termina de fechar e o `v-model` passa a ser `false` em seguida;
+- se o `@update:model-value` recusar a atualização, mantendo o valor `true`, a janela continua fechada com o `v-model` em `true`;
+- se a janela for removida da página antes do fim da animação (por um `v-if`, por exemplo), o `v-model` continua `true`.
+
+Enquanto alguma ação apresenta um indicador de carregamento (`loading`), o usuário não consegue fechar a janela por nenhum desses meios: ela faz uma breve animação, continua aberta e o `v-model` não muda. Exceto no caso do `router.replace` acima, o "voltar" também não sai da página nesse meio tempo. Ações apenas desabilitadas (`disabled`) não impedem o fechamento. A aplicação ainda pode fechar a janela a qualquer momento, atribuindo `false` ao `v-model`.
+
+Em uma página que usa [useUnsavedChanges](../composables/use-unsaved-changes.md) e tem alterações não salvas, o "voltar" é verificado pela página antes da janela, inclusive durante o carregamento: o diálogo "Alterações não salvas" aparece sobre a janela. "Continuar editando" mantém o usuário na página, com a janela aberta, e "Sair sem salvar" sai da página, mesmo que a ação ainda esteja em carregamento.
+
+```vue
+<template>
+  <u-button @click="open = true">Abrir janela</u-button>
+  <p>v-model: {{ open }}</p>
+  <u-dialog v-model="open" title="Fechando a janela">
+    Feche esta janela pela tecla <code>Esc</code> ou clicando fora dela.
+  </u-dialog>
+</template>
+
+<script lang="ts" setup>
+import { ref } from "vue";
+import { UButton, UDialog } from "@nexdom/uimed-vue/components";
+
+const open = ref(false);
+</script>
+```
+
+### Foco
+
+Ao abrir, a janela coloca o foco no primeiro elemento focável do conteúdo, como um campo de formulário, ou, se não houver, na primeira ação. Enquanto a janela está aberta, a tecla `Tab` circula apenas entre os elementos dela. Ao fechar, o foco volta ao elemento que estava focado antes de a janela abrir, como o botão que a abriu.
+
+O título é o nome acessível da janela, anunciado por leitores de tela ao abri-la. Sem título, o conteúdo é anunciado no lugar.
+
+## Propriedades
+
+### Formulários
+
+Para enviar um formulário pelas ações, use uma ação do tipo `submit` com a prop `form` apontando para o `id` do [formulário](./form.md). O evento `submit` do formulário só é disparado quando não há pendências de validação.
+
+Enquanto os dados são salvos, a ação principal pode apresentar um indicador de carregamento (`loading`) e as demais podem ficar desabilitadas (`disabled`). Nesse meio tempo, a janela não fecha pela tecla `Esc`, por um clique fora dela nem pelo botão "voltar": o usuário acompanha o salvamento até o fim, e o exemplo fecha a janela depois de salvar.
+
+O exemplo copia o nome para o rascunho ao abrir a janela, e não ao fechá-la: ao cancelar, a ação passa o `v-model` para `false` enquanto a janela ainda está sumindo, e trocar o texto nesse momento seria visível.
+
+```vue
+<template>
+  <u-button @click="openForm">Editar paciente</u-button>
+  <p>Nome: {{ name }}</p>
+  <u-dialog v-model="open" title="Editar paciente" :actions>
+    <u-form :id="formId" @submit="save">
+      <u-text-field v-model="draft" label="Nome" required />
+    </u-form>
+  </u-dialog>
+</template>
+
+<script lang="ts" setup>
+import { computed, ref, useId } from "vue";
+import type { ComponentProps } from "vue-component-type-helpers";
+import { UButton, UDialog, UForm, UTextField } from "@nexdom/uimed-vue/components";
+
+type DialogAction = NonNullable<ComponentProps<typeof UDialog>["actions"]>[number];
+
+const formId = useId();
+const open = ref(false);
+const isSaving = ref(false);
+const name = ref("Maria da Silva");
+const draft = ref("");
+
+const actions = computed<DialogAction[]>(() => [
+  {
+    label: "Cancelar",
+    variant: "ghost",
+    disabled: isSaving.value,
+    onClick: () => (open.value = false),
+  },
+  { label: "Salvar", type: "submit", form: formId, loading: isSaving.value },
+]);
+
+function openForm() {
+  draft.value = name.value;
+  open.value = true;
+}
+
+function savePatient(): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, 1500));
+}
+
+async function save() {
+  isSaving.value = true;
+  await savePatient();
+  name.value = draft.value;
+  isSaving.value = false;
+  open.value = false;
+}
+</script>
+```
+
+### Tamanhos
+
+A prop `size` define a largura máxima da janela: `small` (400px), `medium` (560px) ou `large` (800px). O padrão é `medium`.
+
+```vue
+<template>
+  <u-button variant="secondary" @click="openSize('small')">Pequena</u-button>
+  <u-button variant="secondary" @click="openSize('medium')">Média</u-button>
+  <u-button variant="secondary" @click="openSize('large')">Grande</u-button>
+  <u-dialog v-model="open" :title="`Tamanho ${size}`" :size :actions>
+    Esta janela usa o tamanho <code>{{ size }}</code
+    >.
+  </u-dialog>
+</template>
+
+<script lang="ts" setup>
+import { ref } from "vue";
+import type { ComponentProps } from "vue-component-type-helpers";
+import { UButton, UDialog } from "@nexdom/uimed-vue/components";
+
+type DialogProps = ComponentProps<typeof UDialog>;
+type DialogSize = NonNullable<DialogProps["size"]>;
+type DialogAction = NonNullable<DialogProps["actions"]>[number];
+
+const open = ref(false);
+const size = ref<DialogSize>("medium");
+
+const actions: DialogAction[] = [{ label: "Fechar", onClick: () => (open.value = false) }];
+
+function openSize(value: DialogSize) {
+  size.value = value;
+  open.value = true;
+}
+</script>
+```
+
+### Conteúdo longo
+
+Quando o conteúdo não cabe na tela, apenas ele rola: o título e as ações continuam visíveis.
+
+```vue
+<template>
+  <u-button @click="open = true">Ler termos</u-button>
+  <u-dialog v-model="open" title="Termos de uso" :actions>
+    <p v-for="index in 20" :key="index">
+      {{ index }}. O paciente autoriza o uso dos seus dados de saúde exclusivamente para fins de
+      atendimento, conforme a legislação vigente.
+    </p>
+  </u-dialog>
+</template>
+
+<script lang="ts" setup>
+import { ref } from "vue";
+import type { ComponentProps } from "vue-component-type-helpers";
+import { UButton, UDialog } from "@nexdom/uimed-vue/components";
+
+type DialogAction = NonNullable<ComponentProps<typeof UDialog>["actions"]>[number];
+
+const open = ref(false);
+
+const actions: DialogAction[] = [
+  { label: "Recusar", variant: "ghost", onClick: () => (open.value = false) },
+  { label: "Aceitar", onClick: () => (open.value = false) },
+];
+</script>
+```
+
+### Confirmações a partir da janela
+
+Diálogos das composables [useDialog](../composables/use-dialog.md) e [useConfirm](../composables/use-confirm.md) abertos por uma ação aparecem sobre a janela. Ao fechá-los, o foco volta para a janela ou, se ela também tiver sido fechada, para o elemento que a abriu.
+
+```vue
+<template>
+  <u-main>
+    <u-button @click="open = true">Ver prontuário</u-button>
+    <p>Prontuário: {{ status }}</p>
+    <u-dialog v-model="open" title="Prontuário" :actions>
+      Maria da Silva, 42 anos. Última consulta em 12/09.
+    </u-dialog>
+  </u-main>
+</template>
+
+<script lang="ts" setup>
+import { computed, ref } from "vue";
+import type { ComponentProps } from "vue-component-type-helpers";
+import { UButton, UDialog, UMain } from "@nexdom/uimed-vue/components";
+import { useConfirm } from "@nexdom/uimed-vue/composables";
+
+type DialogAction = NonNullable<ComponentProps<typeof UDialog>["actions"]>[number];
+
+const { confirm, isRunning } = useConfirm();
+const open = ref(false);
+const status = ref("ativo");
+
+const actions = computed<DialogAction[]>(() => [
+  { label: "Fechar", variant: "ghost", onClick: () => (open.value = false) },
+  { label: "Excluir", color: "danger", loading: isRunning.value, onClick: remove },
+]);
+
+function removeRecord(): Promise<boolean> {
+  return new Promise((resolve) => setTimeout(() => resolve(true), 1500));
+}
+
+async function remove() {
+  const removed = await confirm(
+    {
+      title: "Excluir prontuário",
+      message: "Esta ação não pode ser desfeita.",
+      confirmText: "Excluir",
+      color: "danger",
+    },
+    removeRecord,
+  );
+
+  if (removed) {
+    status.value = "excluído";
+    open.value = false;
+  }
+}
+</script>
+```
+
+## Playground
+
+Experimente as combinações de props do componente.
+
+## Ver também
+
+- Consulte a referência de [API do UDialog](../../api/components/dialog.md) para a lista completa de props, eventos e slots.
+- Para apresentar mensagens ou perguntas simples, use a composable [useDialog](../composables/use-dialog.md).
+- Para confirmar uma ação antes de executá-la, use a composable [useConfirm](../composables/use-confirm.md).

package/skills/uimed-vue/references/guide/components/form.md

@@ -0,0 +1,96 @@
+# Formulários
+
+O componente que engloba os formulários se chama `Form` dentro do uimed-vue.
+
+> [!Warning]
+> Deve ser utilizado no lugar do `<form>` nativo.
+
+## Eventos
+
+### Envio
+
+O evento `submit` é emitido quando o formulário é enviado, repassando o `SubmitEvent` nativo. Ele não é disparado quando restam campos com pendências de validação.
+
+```vue
+<template>
+  <u-section title="Cadastro" :subtitle :actions>
+    <u-section-content>
+      <u-form :id="formId" @submit="onSubmit">
+        <u-text-field label="Nome" required />
+        <u-text-field label="Sobrenome" required />
+      </u-form>
+    </u-section-content>
+  </u-section>
+</template>
+
+<script lang="ts" setup>
+import type { ComponentProps } from "vue-component-type-helpers";
+import { UForm, UTextField, USection, USectionContent } from "@nexdom/uimed-vue/components";
+import { ref, useId, computed } from "vue";
+
+type SectionAction = NonNullable<ComponentProps<typeof USection>["actions"]>[number];
+
+const submits = ref(0);
+const formId = useId();
+
+const subtitle = computed(() => `Pessoa - ${submits.value} envio(s)`);
+
+const actions: SectionAction[] = [{ type: "submit", label: "Enviar", form: formId }];
+
+function onSubmit() {
+  submits.value++;
+  alert("Enviado com sucesso!");
+}
+</script>
+```
+
+### Envio com carregamento
+
+Um botão de envio com `loading` fica desabilitado e não envia o formulário. Quando ele é o primeiro botão de envio do formulário, pressionar `Enter` em um dos campos também não envia o formulário. Isso vale também para os botões de fora do formulário relacionados a ele pela prop `form`, como as ações de uma seção. Assim, basta manter o botão de envio com `loading` enquanto o envio é executado para evitar envios repetidos. Com mais de um botão de envio, mantenha todos com `loading` ou `disabled` durante o envio.
+
+> [!Tip]
+> O `isRunning` do [`useRunOrToast`](../composables/use-run-or-toast.md) pode controlar o `loading` do botão enquanto o envio é executado.
+
+Preencha os campos e pressione `Enter` em um deles, ou clique em "Enviar", para simular um envio de 1,5 segundo.
+
+```vue
+<template>
+  <u-section title="Cadastro" :subtitle :actions>
+    <u-section-content>
+      <u-form :id="formId" @submit="onSubmit">
+        <u-text-field label="Nome" required />
+        <u-text-field label="Sobrenome" required />
+      </u-form>
+    </u-section-content>
+  </u-section>
+</template>
+
+<script lang="ts" setup>
+import type { ComponentProps } from "vue-component-type-helpers";
+import { UForm, UTextField, USection, USectionContent } from "@nexdom/uimed-vue/components";
+import { ref, useId, computed } from "vue";
+
+type SectionAction = NonNullable<ComponentProps<typeof USection>["actions"]>[number];
+
+const submits = ref(0);
+const isSubmitting = ref(false);
+const formId = useId();
+
+const subtitle = computed(() => `Pessoa - ${submits.value} envio(s)`);
+
+const actions = computed<SectionAction[]>(() => [
+  { type: "submit", label: "Enviar", form: formId, loading: isSubmitting.value },
+]);
+
+async function onSubmit() {
+  submits.value++;
+  isSubmitting.value = true;
+  await new Promise((resolve) => setTimeout(resolve, 1500));
+  isSubmitting.value = false;
+}
+</script>
+```
+
+## Ver também
+
+Consulte a referência de [API do UForm](../../api/components/form.md) para a lista completa de props, slots e eventos.

package/skills/uimed-vue/references/guide/components/icon-button.md

@@ -0,0 +1,76 @@
+# Botões de ícone
+
+O componente para botões que exibem apenas um ícone se chama `IconButton`.
+
+Use-o para ações que o ícone basta para identificar, como editar um registro de uma listagem. Quando a ação precisa de um texto para ser entendida, use o [Button](./button.md).
+
+O ícone é ignorado pelos leitores de tela, que anunciam no lugar dele o texto da prop `label`, obrigatória. Por isso, esse texto deve descrever a ação do botão (por exemplo, "Editar paciente"), e não o desenho do ícone (por exemplo, "Lápis").
+
+## Propriedades
+
+### Ícone
+
+A prop `icon`, obrigatória, recebe o nome de um dos ícones listados em [Ícones](../icons.md).
+
+```vue
+<template>
+  <u-icon-button icon="home" label="Início" />
+  <u-icon-button icon="calendar" label="Agenda" />
+  <u-icon-button icon="cogAlternative" label="Configurações" />
+</template>
+
+<script lang="ts" setup>
+import { UIconButton } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+### Cores
+
+A prop `color` aceita um dos valores da paleta do componente: `primary`, `secondary`, `positive`, `informative`, `caution` ou `danger`. O padrão é `primary`.
+
+```vue
+<template>
+  <u-icon-button icon="account" label="Perfil" color="primary" />
+  <u-icon-button icon="cog" label="Configurações" color="secondary" />
+  <u-icon-button icon="calendar" label="Agenda" color="positive" />
+  <u-icon-button icon="fileDocument" label="Documentos" color="informative" />
+  <u-icon-button icon="folder" label="Cadastros" color="caution" />
+  <u-icon-button icon="wallet" label="Financeiro" color="danger" />
+</template>
+
+<script lang="ts" setup>
+import { UIconButton } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+## Eventos
+
+### Clique
+
+O evento `click` é emitido ao clicar no botão, repassando o `MouseEvent` nativo.
+
+```vue
+<template>
+  <u-icon-button icon="accountGroup" label="Adicionar paciente" @click="onClick" />
+  <span>{{ clicks }} paciente(s)</span>
+</template>
+
+<script lang="ts" setup>
+import { ref } from "vue";
+import { UIconButton } from "@nexdom/uimed-vue/components";
+
+const clicks = ref(0);
+
+function onClick() {
+  clicks.value++;
+}
+</script>
+```
+
+## Playground
+
+Experimente as combinações de props do componente.
+
+## Ver também
+
+Consulte a referência de [API do UIconButton](../../api/components/icon-button.md) para a lista completa de props e eventos, e [Ícones](../icons.md) para todos os ícones disponíveis.

package/skills/uimed-vue/references/guide/components/img.md

@@ -0,0 +1,128 @@
+# Imagens
+
+O componente padrão para exibir imagens se chama `Img`.
+
+> [!Warning]
+> Deve ser utilizado no lugar do `<img>` nativo.
+
+As imagens são decorativas: leitores de tela as ignoram. Quando a imagem transmite informação, apresente essa informação também em texto na página.
+
+Por padrão, a imagem só é carregada quando está prestes a aparecer na tela. Até lá, e enquanto ela carrega, o espaço reservado para ela fica vazio. Informe as dimensões da imagem (`width` e `height`, ou `aspectRatio`) para reservar esse espaço e evitar que o conteúdo da página se desloque quando ela aparecer.
+
+> [!Warning]
+> Coloque a imagem dentro de uma `UColumn`. Diretamente dentro de uma `URow`, sem coluna, a imagem ignora a `width` e ocupa toda a largura da linha.
+
+## Propriedades
+
+### Dimensões
+
+As props `width` e `height` definem a largura e a altura da imagem e reservam esse espaço antes de ela carregar. Números são medidas em pixels, e textos aceitam qualquer unidade CSS, como `"50%"`, relativa à largura da coluna.
+
+Dentro de uma `UColumn`, a largura nunca ultrapassa a da coluna: quando é maior, a imagem encolhe até a largura da coluna, mantendo a altura informada.
+
+```vue
+<template>
+  <u-row>
+    <u-column>
+      <u-img src="/logo.svg" :width="187" :height="239" />
+    </u-column>
+  </u-row>
+</template>
+
+<script lang="ts" setup>
+import { UColumn, UImg, URow } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+Com uma porcentagem em `width` e uma `aspectRatio`, a imagem acompanha a largura da coluna e mantém a proporção.
+
+```vue
+<template>
+  <u-row>
+    <u-column>
+      <u-img src="/foto.jpg" width="50%" :aspect-ratio="3 / 4" />
+    </u-column>
+  </u-row>
+</template>
+
+<script lang="ts" setup>
+import { UColumn, UImg, URow } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+### Proporção
+
+A prop `aspectRatio` define a proporção entre a largura e a altura da imagem (por exemplo, `16 / 9`). A altura é calculada a partir da largura, então o espaço é reservado mesmo quando a largura depende da coluna.
+
+Sem `width`, a imagem ocupa toda a largura da coluna. Quando `height` também é informada, ela prevalece sobre a `aspectRatio`.
+
+```vue
+<template>
+  <u-row>
+    <u-column cols="4">
+      <u-img src="/foto.jpg" :aspect-ratio="3 / 4" />
+    </u-column>
+    <u-column cols="8">
+      <u-img src="/foto.jpg" :width="120" :aspect-ratio="3 / 4" />
+    </u-column>
+  </u-row>
+</template>
+
+<script lang="ts" setup>
+import { UColumn, UImg, URow } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+### Preenchimento
+
+Por padrão, a imagem é exibida por inteiro dentro do espaço reservado, que pode ficar com sobras quando a proporção da imagem é diferente da do espaço.
+
+A prop `cover` faz a imagem preencher todo o espaço, recortando o que exceder. Ela só faz diferença quando a proporção do espaço é definida, com `width` e `height` ou com `aspectRatio`.
+
+```vue
+<template>
+  <u-row>
+    <u-column cols="6">
+      <u-img src="/foto.jpg" :width="240" :height="160" />
+    </u-column>
+    <u-column cols="6">
+      <u-img src="/foto.jpg" :width="240" :height="160" cover />
+    </u-column>
+  </u-row>
+</template>
+
+<script lang="ts" setup>
+import { UColumn, UImg, URow } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+### Carregamento imediato
+
+Por padrão, a imagem só é carregada quando está prestes a aparecer na tela, o que economiza dados em páginas com muitas imagens.
+
+A prop `eager` carrega a imagem assim que a página é aberta. Use-a em imagens visíveis desde a abertura da página, como a logo de uma tela de login.
+
+```vue
+<template>
+  <u-row>
+    <u-column cols="6">
+      <u-img src="/foto.jpg" :width="120" :height="160" />
+    </u-column>
+    <u-column cols="6">
+      <u-img src="/foto.jpg" :width="120" :height="160" eager />
+    </u-column>
+  </u-row>
+</template>
+
+<script lang="ts" setup>
+import { UColumn, UImg, URow } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+## Playground
+
+Experimente as combinações de props do componente.
+
+## Ver também
+
+Consulte a referência de [API do UImg](../../api/components/img.md) para a lista completa de props.