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

package/skills/uimed-vue/references/guide/components/autocomplete-field.md

@@ -0,0 +1,256 @@
+# Campos com preenchimento automático
+
+O componente para campos com preenchimento automático (autocomplete) se chama `AutocompleteField`.
+
+> [!Warning]
+> Deve ser utilizado no lugar do `<select>` nativo ou da combinação `<input>` com lista de sugestões.
+
+## Propriedades
+
+### Variantes
+
+A prop `variant` define a variação de estilo aplicada ao campo. O padrão é `primary`.
+
+```vue
+<template>
+  <u-autocomplete-field
+    label="Primary"
+    variant="primary"
+    :items="['Brasil', 'Portugal', 'Moçambique']"
+  />
+  <u-autocomplete-field
+    label="Secondary"
+    variant="secondary"
+    :items="['Brasil', 'Portugal', 'Moçambique']"
+  />
+</template>
+
+<script lang="ts" setup>
+import { UAutocompleteField } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+### Labels
+
+A prop `label` aceita um texto que identifica a informação a ser preenchida no campo.
+
+```vue
+<template>
+  <u-autocomplete-field label="País" :items="['Brasil', 'Portugal']" />
+  <u-autocomplete-field label="Cidade" :items="['São Paulo', 'Rio de Janeiro']" />
+</template>
+
+<script lang="ts" setup>
+import { UAutocompleteField } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+### Placeholders
+
+A prop `placeholder` aceita um texto que fornece um exemplo ou instrução sobre o dado que pode ser selecionado no campo.
+
+```vue
+<template>
+  <u-autocomplete-field
+    label="Selecione um país"
+    placeholder="Ex: Brasil"
+    :items="['Brasil', 'Portugal', 'Moçambique']"
+  />
+</template>
+
+<script lang="ts" setup>
+import { UAutocompleteField } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+### Mensagens
+
+A prop `hint` recebe um texto que será apresentado como uma dica para oferecer mais instruções ao usuário.
+
+```vue
+<template>
+  <u-autocomplete-field
+    label="País"
+    hint="Selecione um país da lista"
+    :items="['Brasil', 'Portugal', 'Moçambique']"
+  />
+</template>
+
+<script lang="ts" setup>
+import { UAutocompleteField } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+### Estados
+
+#### Desabilitado
+
+Utilize a prop `disabled` para indicar ao usuário que não há possibilidade de interação com o campo.
+
+```vue
+<template>
+  <u-autocomplete-field label="Desabilitado" disabled :items="['Brasil', 'Portugal']" />
+</template>
+
+<script lang="ts" setup>
+import { UAutocompleteField } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+#### Somente leitura
+
+Utilize a prop `readonly` para evitar que o valor presente em um campo seja alterado.
+
+```vue
+<template>
+  <u-autocomplete-field
+    modelValue="Brasil"
+    label="Somente leitura"
+    readonly
+    :items="['Brasil', 'Portugal']"
+  />
+</template>
+
+<script lang="ts" setup>
+import { UAutocompleteField } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+#### Carregamento
+
+A prop `loading` exibe um indicador de carregamento no campo enquanto ativa. Nesse estado, o campo mantém o rótulo como nome acessível e fica marcado como ocupado, e leitores de tela ignoram o indicador.
+
+```vue
+<template>
+  <u-autocomplete-field label="Carregando" loading :items="['Brasil', 'Portugal']" />
+</template>
+
+<script lang="ts" setup>
+import { UAutocompleteField } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+#### Limpável
+
+A prop `clearable` exibe um recurso para limpar o campo.
+
+```vue
+<template>
+  <u-autocomplete-field label="Limpável" clearable :items="['Brasil', 'Portugal']" />
+</template>
+
+<script lang="ts" setup>
+import { UAutocompleteField } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+## Comportamentos específicos
+
+### Modo restrito vs digitação livre
+
+A prop `strict` controla o comportamento do campo:
+
+- Quando `strict` é `false` (padrão), permite digitar valores não presentes na lista
+- Quando `strict` é `true`, força a seleção de itens da lista
+
+```vue
+<template>
+  <u-autocomplete-field
+    label="Modo freeform"
+    :strict="false"
+    :items="['Brasil', 'Portugal', 'Moçambique']"
+  />
+  <u-autocomplete-field
+    label="Modo restrito"
+    :strict="true"
+    :items="['Brasil', 'Portugal', 'Moçambique']"
+  />
+</template>
+
+<script lang="ts" setup>
+import { UAutocompleteField } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+### Seleção múltipla
+
+A prop `multiple` permite a seleção de mais de um valor.
+
+```vue
+<template>
+  <u-autocomplete-field
+    v-model="multipleValue"
+    label="Selecione países"
+    :multiple="true"
+    :items="['Brasil', 'Portugal', 'Moçambique']"
+  />
+</template>
+
+<script lang="ts" setup>
+import { ref } from "vue";
+import { UAutocompleteField } from "@nexdom/uimed-vue/components";
+
+const multipleValue = ref<string[]>([]);
+</script>
+```
+
+### Itens com label e value
+
+Os itens podem ser objetos com `label` (texto exibido) e `value` (valor interno).
+
+```vue
+<template>
+  <u-autocomplete-field label="País" :items="countryItems" />
+</template>
+
+<script lang="ts" setup>
+import { UAutocompleteField } from "@nexdom/uimed-vue/components";
+
+const countryItems = [
+  { label: "Brasil", value: "BR" },
+  { label: "Portugal", value: "PT" },
+  { label: "Moçambique", value: "MZ" },
+];
+</script>
+```
+
+## Eventos
+
+### Atualização
+
+O evento `update:modelValue` será emitido toda vez que o valor do campo for alterado pelo usuário.
+
+```vue
+<template>
+  <u-autocomplete-field
+    label="País"
+    :model-value
+    :hint
+    :items="items"
+    @update:modelValue="onUpdateValue"
+  />
+</template>
+
+<script lang="ts" setup>
+import { ref, computed } from "vue";
+import { UAutocompleteField } from "@nexdom/uimed-vue/components";
+
+const items = ["Brasil", "Portugal"];
+const modelValue = ref("Brasil");
+const changes = ref(0);
+const hint = computed(() => `${changes.value} alteração(ões)`);
+
+function onUpdateValue(newValue: string | undefined) {
+  modelValue.value = newValue ?? "";
+  changes.value++;
+}
+</script>
+```
+
+## Playground
+
+Experimente as combinações de props do componente.
+
+## Ver também
+
+Consulte a referência de [API do UAutocompleteField](../../api/components/autocomplete-field.md) para a lista completa de props, slots e eventos.

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

@@ -0,0 +1,155 @@
+# Botões
+
+O componente padrão para botões se chama `Button`.
+
+> [!Warning]
+> Deve ser utilizado no lugar do `<button>` nativo.
+
+## Propriedades
+
+### Variantes
+
+A prop `variant` define a variação de estilo aplicada ao botão. O padrão é `primary`.
+
+```vue
+<template>
+  <u-button variant="primary">Primary</u-button>
+  <u-button variant="secondary">Secondary</u-button>
+  <u-button variant="ghost">Ghost</u-button>
+</template>
+
+<script lang="ts" setup>
+import { UButton } 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`.
+
+```vue
+<template>
+  <u-button color="primary">Primary</u-button>
+  <u-button color="secondary">Secondary</u-button>
+  <u-button color="positive">Positive</u-button>
+  <u-button color="informative">Informative</u-button>
+  <u-button color="caution">Caution</u-button>
+  <u-button color="danger">Danger</u-button>
+</template>
+
+<script lang="ts" setup>
+import { UButton } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+### Estados
+
+#### Desabilitado
+
+Utilize a prop `disabled` para remover a possibilidade de clicar ou focar no botão.
+
+```vue
+<template>
+  <u-button disabled>Desabilitado</u-button>
+</template>
+
+<script lang="ts" setup>
+import { UButton } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+#### Carregamento
+
+A prop `loading` exibe um indicador de carregamento e desabilita o botão enquanto ativa, assim como a prop `disabled`: não é possível clicar ou focar no botão, o evento `click` não é disparado e o formulário do botão não é enviado. Nesse estado, o botão tem a aparência de desabilitado, com o indicador de carregamento, e, se estiver focado, perde o foco ao entrar em carregamento, como qualquer botão desabilitado. O botão mantém o texto como nome acessível e fica marcado como ocupado, e leitores de tela ignoram o indicador. Veja também o [envio com carregamento](./form.md#envio-com-carregamento) de formulários.
+
+Clique no botão abaixo para simular uma ação de 1,5 segundo. Novos cliques são ignorados enquanto ela é executada.
+
+```vue
+<template>
+  <u-button :loading="isSaving" @click="onSave">Salvar</u-button>
+  <span>{{ saves }} salvamento(s)</span>
+</template>
+
+<script lang="ts" setup>
+import { ref } from "vue";
+import { UButton } from "@nexdom/uimed-vue/components";
+
+const saves = ref(0);
+const isSaving = ref(false);
+
+async function onSave() {
+  saves.value++;
+  isSaving.value = true;
+  await new Promise((resolve) => setTimeout(resolve, 1500));
+  isSaving.value = false;
+}
+</script>
+```
+
+### Largura total
+
+Utilize a prop `fullWidth` (`full-width` no template) para fazer o botão ocupar 100% da largura do elemento em que está, como a única ação de um formulário em telas pequenas.
+
+```vue
+<template>
+  <u-button full-width>Largura total</u-button>
+</template>
+
+<script lang="ts" setup>
+import { UButton } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+### Navegação
+
+A prop `route` faz o botão navegar ao ser clicado. Nesse caso, ele é exibido como um link, com a aparência de botão. Uma rota da aplicação, como `"/pacientes"` ou `{ name: "paciente", params: { id: 42 } }`, navega sem recarregar a página. Enquanto essa rota é a página atual, o botão mantém a aparência e é anunciado como a página atual pelos leitores de tela. Um endereço que começa com `http` navega pelo navegador, na mesma aba.
+
+O evento `click` continua sendo disparado ao clicar no botão. As props `type` e `form` não se aplicam a links e são ignoradas. Enquanto `disabled` ou `loading`, o botão não navega: ele é exibido como um botão desabilitado, sem link.
+
+> [!Warning]
+> Rotas da aplicação só funcionam em aplicações que usam o [Vue Router](https://router.vuejs.org/).
+
+```vue
+<template>
+  <u-button route="/pacientes">Pacientes</u-button>
+  <u-button :route="{ name: 'paciente' }">Paciente</u-button>
+  <u-button :route="sharedDocs">Documentação do Shared</u-button>
+</template>
+
+<script lang="ts" setup>
+import { UButton } from "@nexdom/uimed-vue/components";
+
+const sharedDocs = "https://nexdom-healthtech.github.io/shared/";
+</script>
+```
+
+## Eventos
+
+### Clique
+
+O evento `click` é emitido ao clicar no botão, repassando o `MouseEvent` nativo. Ele não é disparado quando o botão está `disabled` ou `loading`.
+
+```vue
+<template>
+  <u-button @click="onClick">Me clique</u-button>
+</template>
+
+<script lang="ts" setup>
+import { ref } from "vue";
+import { UButton } 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 UButton](../../api/components/button.md) para a lista completa de props, slots e eventos.

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

@@ -0,0 +1,113 @@
+# Caixas de seleção
+
+O componente para caixas de seleção se chama `Checkbox`.
+
+> [!Warning]
+> Deve ser utilizado no lugar do `<input>` nativo do tipo `checkbox`.
+
+## Propriedades
+
+### Labels
+
+A prop `label` aceita um texto que identifica a informação a ser selecionada na caixa.
+
+```vue
+<template>
+  <u-checkbox label="Aceito os termos de uso" />
+  <u-checkbox label="Concordo com a política de privacidade" />
+</template>
+
+<script lang="ts" setup>
+import { UCheckbox } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+### Estados
+
+#### Desabilitado
+
+Utilize a prop `disabled` para indicar ao usuário que não há possibilidade de interação com a caixa de seleção.
+
+```vue
+<template>
+  <u-checkbox label="Desabilitado" disabled />
+</template>
+
+<script lang="ts" setup>
+import { UCheckbox } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+#### Somente leitura
+
+Utilize a prop `readonly` para evitar que o valor presente em uma caixa de seleção seja alterado.
+
+```vue
+<template>
+  <u-checkbox :model-value="true" label="Somente leitura (marcado)" readonly />
+</template>
+
+<script lang="ts" setup>
+import { UCheckbox } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+### Valores customizados
+
+Por padrão, quando marcada, a caixa de seleção aplica o valor `true` ao modelo, e quando desmarcada, aplica `false`. É possível customizar esses valores utilizando as props `trueValue` e `falseValue`.
+
+```vue
+<template>
+  <u-checkbox
+    v-model="customValuesCheckbox"
+    :label="customValuesCheckbox"
+    true-value="Ativado"
+    false-value="Desativado"
+  />
+</template>
+
+<script lang="ts" setup>
+import { ref } from "vue";
+import { UCheckbox } from "@nexdom/uimed-vue/components";
+
+const customValuesCheckbox = ref("Ativado");
+</script>
+```
+
+## Eventos
+
+### Atualização
+
+O evento `update:modelValue` será emitido toda vez que o valor da caixa for alterado pelo usuário, repassando o novo valor.
+
+```vue
+<template>
+  <u-checkbox
+    label="Marque para se cadastrar"
+    :model-value="modelValue"
+    @update:modelValue="onUpdateValue"
+  />
+  {{ changes }} alteração(ões)
+</template>
+
+<script lang="ts" setup>
+import { ref } from "vue";
+import { UCheckbox } from "@nexdom/uimed-vue/components";
+
+const modelValue = ref(false);
+const changes = ref(0);
+
+function onUpdateValue(newValue: boolean | undefined) {
+  modelValue.value = newValue ?? false;
+  changes.value++;
+}
+</script>
+```
+
+## Playground
+
+Experimente as combinações de props do componente.
+
+## Ver também
+
+Consulte a referência de [API do UCheckbox](../../api/components/checkbox.md) para a lista completa de props, slots e eventos.