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

package/skills/uimed-vue/references/guide/components/page-transition.md

@@ -0,0 +1,111 @@
+# Transição de páginas
+
+O componente para animar a troca entre as páginas da aplicação se chama `PageTransition`. A página atual desaparece aos poucos e, só depois que ela sai, a nova página aparece da mesma forma.
+
+> [!Warning]
+> Feito para envolver a página renderizada pelo `<router-view>` do [Vue Router](https://router.vuejs.org/).
+
+## Uso
+
+Coloque o `<router-view>` dentro do [Componente base](./main.md) e envolva a página da rota atual com o `PageTransition`.
+
+Só a troca de páginas é animada. A primeira página aparece sem animação quando a aplicação é montada depois que o roteador carrega a primeira rota (com `await router.isReady()` antes do `app.mount`). Se a aplicação for montada antes, a área de conteúdo começa vazia e a primeira página aparece com a animação, como na demonstração abaixo.
+
+Navegue entre as páginas da demonstração.
+
+A demonstração tem duas páginas com um roteador próprio. Por isso, a navegação entre elas não altera o endereço do navegador. A página "Pacientes" é uma section, e a página "Agenda" centraliza a sua section na altura da tela, com um container e uma linha com `full-height` (veja [Altura total](./layout.md#altura-total)).
+
+```vue
+<!-- App.vue -->
+<template>
+  <u-main>
+    <router-view v-slot="{ Component }">
+      <u-page-transition>
+        <component :is="Component" />
+      </u-page-transition>
+    </router-view>
+  </u-main>
+</template>
+
+<script lang="ts" setup>
+import { UMain, UPageTransition } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+### Elemento em volta da página
+
+O `PageTransition` coloca a página dentro de um `<div>`, e é esse elemento que aparece e desaparece. Assim, qualquer página é animada, seja qual for o seu conteúdo: uma section, mais de um elemento (por exemplo, o conteúdo e uma [janela modal](./dialog.md) ao lado dele) ou comentários fora do elemento principal.
+
+```vue
+<!-- PatientList.vue, página renderizada pelo <router-view> -->
+<template>
+  <u-section title="Pacientes" :actions>
+    <u-section-content>Lista de pacientes cadastrados.</u-section-content>
+  </u-section>
+  <u-dialog v-model="open" title="Novo paciente">...</u-dialog>
+</template>
+```
+
+O `<div>` ocupa toda a altura do elemento em que está. Por isso, containers e linhas com `full-height` continuam ocupando a altura da área de conteúdo do [Componente base](./main.md), como na página "Agenda" da demonstração.
+
+Atributos informados no `PageTransition`, como `class` e `style`, não são repassados ao `<div>` nem à página.
+
+### Movimento reduzido
+
+Quando o sistema operacional pede movimento reduzido (por exemplo, com a opção "Reduzir movimento" ou "Efeitos de animação" desligada), as páginas trocam sem animação. Nenhuma configuração é necessária, e a mudança da preferência com a aplicação aberta vale a partir da troca seguinte.
+
+### Quando a troca é animada
+
+A troca é animada sempre que a prop `transitionKey` muda. Por padrão, ela é o endereço completo da rota atual (`route.fullPath`), então toda navegação é animada, inclusive quando só mudam os parâmetros (de `/pacientes/1` para `/pacientes/2`), a consulta (de `/pacientes?pagina=1` para `/pacientes?pagina=2`) ou o fragmento (um link para uma âncora da mesma página, como `#consultas`). Nesses casos, a página é criada de novo, e o estado dela (como campos preenchidos) não é mantido.
+
+Para escolher quais navegações são animadas, informe outro valor. Com o caminho da rota (`route.path`), por exemplo, mudanças só na consulta ou no fragmento, como a troca de página de uma lista, acontecem sem animação e mantêm a página:
+
+```vue
+<template>
+  <u-main>
+    <router-view v-slot="{ Component, route }">
+      <u-page-transition :transition-key="route.path">
+        <component :is="Component" />
+      </u-page-transition>
+    </router-view>
+  </u-main>
+</template>
+```
+
+#### Rotas aninhadas
+
+Com rotas aninhadas, o endereço completo também muda quando só a rota filha muda. Com o valor padrão, navegar entre rotas filhas (de `/pacientes/1` para `/pacientes/2`) anima a página pai inteira, que sai com a filha anterior e é criada de novo com a nova, sem manter o seu estado.
+
+Para animar só a troca da rota filha, informe no `PageTransition` de cima uma `transitionKey` que identifique apenas a rota pai, como o caminho dela (`route.matched[0]?.path`), e envolva o `<router-view>` da página pai com outro `PageTransition`:
+
+```vue
+<!-- App.vue -->
+<template>
+  <u-main>
+    <router-view v-slot="{ Component, route }">
+      <u-page-transition :transition-key="route.matched[0]?.path">
+        <component :is="Component" />
+      </u-page-transition>
+    </router-view>
+  </u-main>
+</template>
+```
+
+```vue
+<!-- PatientLayout.vue, página pai das rotas /pacientes/:id -->
+<template>
+  <router-view v-slot="{ Component }">
+    <u-page-transition>
+      <component :is="Component" />
+    </u-page-transition>
+  </router-view>
+</template>
+```
+
+### Páginas mantidas em memória
+
+Com um `<keep-alive>` dentro do `PageTransition`, a troca é animada, mas as páginas não são mantidas: o `<div>` em volta da página é criado de novo a cada troca, e o `<keep-alive>` dentro dele também. Para manter as páginas, informe uma `transitionKey` fixa (por exemplo, `transition-key="paginas"`). Nesse caso, a troca de páginas acontece sem animação.
+
+## Ver também
+
+Consulte a referência de [API do UPageTransition](../../api/components/page-transition.md) para mais informações.

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

@@ -0,0 +1,232 @@
+# Agrupador de Conteúdo
+
+O componente padrão para agrupar conteúdo relacionado se chama `Section`.
+
+> [!Warning]
+> Deve ser utilizado no lugar do `<section>` nativo.
+
+Dentro do mesmo também podemos adicionar o [`SectionContent`](#componente-sectioncontent).
+
+## Propriedades
+
+### Variantes
+
+A prop `variant` define a variação de estilo aplicada ao agrupador de conteúdo. O padrão é `primary`.
+
+```vue
+<template>
+  <u-section variant="primary" title="Primary">Conteúdo do agrupador primary</u-section>
+  <u-section variant="secondary" title="Secondary">Conteúdo do agrupador secondary</u-section>
+</template>
+
+<script lang="ts" setup>
+import { USection } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+### Título e Subtítulo
+
+As props `title` e `subtitle` definem o título e o subtítulo exibidos no topo do agrupador.
+
+```vue
+<template>
+  <u-section title="Título do Agrupador" subtitle="Subtítulo descritivo">
+    Conteúdo do agrupador com título e subtítulo
+  </u-section>
+</template>
+
+<script lang="ts" setup>
+import { USection } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+### Alinhamento
+
+A prop `textAlign` define o alinhamento horizontal do título, do subtítulo, do conteúdo e das ações do agrupador. O padrão é `start`.
+
+- `start`: alinha o texto ao início, mantendo as ações no fim;
+- `center`: centraliza o texto e as ações;
+- `end`: alinha o texto e as ações ao fim.
+
+Os valores `start` e `end` seguem a direção do texto, então se invertem em idiomas escritos da direita para a esquerda.
+
+```vue
+<template>
+  <u-section text-align="start" title="Início" subtitle="Alinhamento padrão" :actions="actions">
+    <u-section-content>Conteúdo alinhado ao início, com as ações no fim</u-section-content>
+  </u-section>
+  <u-section
+    text-align="center"
+    title="Página não encontrada"
+    subtitle="Erro 404"
+    :actions="notFoundActions"
+  >
+    <u-section-content>
+      O endereço que você tentou abrir não existe ou foi removido.
+    </u-section-content>
+  </u-section>
+  <u-section text-align="end" title="Fim" subtitle="Alinhado ao fim" :actions="actions">
+    <u-section-content>Conteúdo alinhado ao fim, assim como as ações</u-section-content>
+  </u-section>
+</template>
+
+<script lang="ts" setup>
+import { ref } from "vue";
+import { USection, USectionContent } from "@nexdom/uimed-vue/components";
+
+const actions = ref([
+  {
+    label: "Cancelar",
+    variant: "ghost",
+    onClick: () => alert("Cancelar clicado"),
+  },
+  {
+    label: "Salvar",
+    color: "positive",
+    onClick: () => alert("Salvar clicado"),
+  },
+]);
+
+const notFoundActions = ref([
+  {
+    label: "Voltar para o Início",
+    variant: "ghost",
+    onClick: () => alert("Voltar para o Início clicado"),
+  },
+]);
+</script>
+```
+
+O alinhamento vale para todo o conteúdo do agrupador, inclusive para os textos e componentes dentro dele, exceto os que definem o próprio alinhamento. Por isso, os valores `center` e `end` são pensados para conteúdos curtos, como estados vazios e mensagens.
+
+Um agrupador dentro de outro mantém o próprio alinhamento, que também é `start` por padrão:
+
+```vue
+<template>
+  <u-section text-align="center" title="Agrupador centralizado" full-width>
+    <u-section-content>
+      <p>Conteúdo centralizado</p>
+      <u-section variant="secondary" title="Agrupador interno" full-width>
+        <u-section-content>Conteúdo alinhado ao início</u-section-content>
+      </u-section>
+    </u-section-content>
+  </u-section>
+</template>
+
+<script lang="ts" setup>
+import { USection, USectionContent } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+### Dimensões
+
+#### Largura Total
+
+Utilize a prop `fullWidth` para fazer o agrupador ocupar 100% da largura do seu container.
+
+```vue
+<template>
+  <u-section title="Agrupador com 100% de largura" full-width>
+    Conteúdo preenchendo toda a largura disponível
+  </u-section>
+</template>
+
+<script lang="ts" setup>
+import { USection } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+#### Altura Total
+
+Utilize a prop `fullHeight` para fazer o agrupador ocupar 100% da altura do seu container.
+
+Quando o agrupador estiver dentro de uma [`URow`](./layout.md#alinhamento-vertical-das-colunas), utilize `align-y="stretch"` na linha para que ele acompanhe a altura da coluna mais alta. Para que a linha ocupe toda a altura da tela, veja [Altura total](./layout.md#altura-total).
+
+```vue
+<template>
+  <div style="height: 300px;">
+    <u-section title="Agrupador com 100% de altura" full-height>
+      Conteúdo preenchendo toda a altura disponível
+    </u-section>
+  </div>
+</template>
+
+<script lang="ts" setup>
+import { USection } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+### Ações
+
+A prop `actions` define uma lista de botões exibidos na área de ações (rodapé) do agrupador, alinhados ao fim (veja [Alinhamento](#alinhamento)), nesta ordem. Coloque a ação principal por último. Cada ação aceita as props do [Button](./button.md), como `variant`, `color`, `disabled` e `route`, que faz a ação navegar para uma rota (veja [Navegação](./button.md#navegacao)).
+
+Coloque o conteúdo dentro do [`SectionContent`](#componente-sectioncontent) para que ele fique espaçado das bordas do agrupador e dos botões de ação.
+
+```vue
+<template>
+  <div style="height: 300px;">
+    <u-section title="Agrupador com Ações" :actions="actions" full-height>
+      <u-section-content>Conteúdo com ações disponíveis no rodapé</u-section-content>
+    </u-section>
+  </div>
+</template>
+
+<script lang="ts" setup>
+import { ref } from "vue";
+import { USection, USectionContent } from "@nexdom/uimed-vue/components";
+
+const actions = ref([
+  {
+    label: "Cancelar",
+    variant: "ghost",
+    onClick: () => alert("Cancelar clicado"),
+  },
+  {
+    label: "Salvar",
+    color: "positive",
+    onClick: () => alert("Salvar clicado"),
+  },
+]);
+</script>
+```
+
+### Carregamento
+
+A prop `loading` exibe um skeleton loader no lugar do conteúdo enquanto uma operação está em andamento.
+
+```vue
+<template>
+  <u-section title="Carregando..." loading> Conteúdo do agrupador </u-section>
+  <u-section title="Carregando com actions..." :actions="[{ label: 'Salvar' }]" loading>
+    <u-section-content>Conteúdo do agrupador com actions</u-section-content>
+  </u-section>
+</template>
+
+<script lang="ts" setup>
+import { USection, USectionContent } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+## Componente SectionContent
+
+O componente `SectionContent` é utilizado para estruturar o conteúdo exibido dentro do `Section`.
+
+```vue
+<template>
+  <u-section title="Título do Agrupador">
+    <u-section-content>Conteúdo estruturado com o componente SectionContent</u-section-content>
+  </u-section>
+</template>
+
+<script lang="ts" setup>
+import { USectionContent, USection } 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 USection](../../api/components/sections/section.md) e da [API do USectionContent](../../api/components/sections/section-content.md) para a lista completa de props, slots e eventos.

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

@@ -0,0 +1,102 @@
+# Tabela
+
+O componente `Table` é usado para apresentar dados em tabelas, de forma clara e organizada.
+
+> [!Warning]
+> Deve ser utilizado no lugar do `<table>` nativo.
+
+## Propriedades
+
+### Layout
+
+A prop `vertical` define o layout da tabela.
+
+#### Horizontal (Padrão)
+
+Por padrão, a tabela será exibida em layout horizontal com cabeçalhos no topo.
+
+```vue
+<template>
+  <u-table
+    :headers="['Nome', 'Idade', 'Cidade']"
+    :items="[
+      ['Ana', '30', 'São Paulo'],
+      ['Bruno', '25', 'Rio de Janeiro'],
+    ]"
+  />
+</template>
+
+<script lang="ts" setup>
+import { UTable } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+#### Vertical
+
+Utilize a prop `vertical` para renderizar uma tabela separada para cada item, exibindo cada linha com um cabeçalho na coluna esquerda.
+
+```vue
+<template>
+  <u-table
+    :headers="['Nome', 'Idade', 'Cidade']"
+    :items="[
+      ['Ana', '30', 'São Paulo'],
+      ['Bruno', '25', 'Rio de Janeiro'],
+    ]"
+    vertical
+  />
+</template>
+
+<script lang="ts" setup>
+import { UTable } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+Caso `headers` seja um array vazio, o layout vertical ainda pode ser utilizado, mas as linhas serão exibidas sem um cabeçalho na coluna esquerda.
+
+```vue
+<template>
+  <u-table
+    :items="[
+      ['Ana', '30', 'São Paulo'],
+      ['Bruno', '25', 'Rio de Janeiro'],
+    ]"
+    vertical
+  />
+</template>
+
+<script lang="ts" setup>
+import { UTable } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+### Carregamento
+
+A prop `loading` exibe um skeleton loader no lugar da tabela.
+
+Esse é um ótimo recurso de feedback para o usuário, enquanto uma operação está em andamento.
+
+```vue
+<template>
+  <u-table
+    :headers="['Nome', 'Idade', 'Cidade']"
+    :items="[
+      ['Ana', '30', 'São Paulo'],
+      ['Bruno', '25', 'Rio de Janeiro'],
+    ]"
+    loading
+  />
+</template>
+
+<script lang="ts" setup>
+import { UTable } 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 UTable](../../api/components/table.md) para a lista completa de props.

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

@@ -0,0 +1,172 @@
+# Campos de texto
+
+O componente para campos de texto se chama `TextField`.
+
+> [!Warning]
+> Deve ser utilizado no lugar do `<input>` nativo.
+
+## Propriedades
+
+### Variantes
+
+A prop `variant` define a variação de estilo aplicada ao campo. O padrão é `primary`.
+
+```vue
+<template>
+  <u-text-field label="Primary" variant="primary" />
+  <u-text-field label="Secondary" variant="secondary" />
+</template>
+
+<script lang="ts" setup>
+import { UTextField } 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-text-field label="Primeiro nome" />
+  <u-text-field label="Sobrenome" />
+</template>
+
+<script lang="ts" setup>
+import { UTextField } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+### Placeholders
+
+A prop `placeholder` aceita um texto que fornece um exemplo ou instrução sobre o formato do dado que pode ser preenchido no campo.
+
+```vue
+<template>
+  <u-text-field label="E-mail" type="email" placeholder="me.nexdom@gmail.com" />
+</template>
+
+<script lang="ts" setup>
+import { UTextField } 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 que virá a preencher o campo.
+
+```vue
+<template>
+  <u-text-field label="URL" type="url" hint="https://google.com ou http://localhost:8080" />
+</template>
+
+<script lang="ts" setup>
+import { UTextField } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+### Senha
+
+Com `type="password"`, o campo oculta o valor digitado e exibe um ícone de olho, anunciado pelos leitores de tela como o botão "Mostrar senha", que alterna entre mostrar e ocultar a senha. O ícone também pode ser acessado pelo teclado: a partir do campo, pressione `Tab` para focá-lo e `Espaço` ou `Enter` para alternar. A senha volta a ficar oculta ao pressionar o ícone novamente ou quando o `type` muda.
+
+```vue
+<template>
+  <u-text-field label="Senha" type="password" />
+</template>
+
+<script lang="ts" setup>
+import { UTextField } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+### Pesquisa
+
+Com `type="search"`, o campo exibe um ícone de lupa e, por padrão, o recurso para limpar o valor digitado (`clearable`). A lupa é apenas visual: não é anunciada pelos leitores de tela e não recebe foco ao pressionar `Tab`.
+
+```vue
+<template>
+  <u-text-field label="Pesquisar" type="search" />
+</template>
+
+<script lang="ts" setup>
+import { UTextField } 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-text-field label="Desabilitado" disabled />
+</template>
+
+<script lang="ts" setup>
+import { UTextField } 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-text-field modelValue="Valor inicial" label="Somente leitura" readonly />
+</template>
+
+<script lang="ts" setup>
+import { UTextField } 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-text-field label="Carregando" loading />
+</template>
+
+<script lang="ts" setup>
+import { UTextField } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+## Eventos
+
+### Atualização
+
+O evento `update:modelValue` será emitido toda vez que o valor do campo for alterado pelo usuário, repassando o novo valor como uma `string`.
+
+```vue
+<template>
+  <u-text-field label="Texto" :model-value :hint @update:modelValue="onUpdateValue" />
+</template>
+
+<script lang="ts" setup>
+import { ref, computed } from "vue";
+import { UTextField } from "@nexdom/uimed-vue/components";
+
+const modelValue = ref("Me altere!");
+const changes = ref(0);
+const hint = computed(() => `${changes.value} alteração(ões)`);
+
+function onUpdateValue(newValue: string) {
+  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 UTextField](../../api/components/text-field.md) para a lista completa de props, slots e eventos.