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

package/skills/uimed-vue/references/guide/components/data-set.md

@@ -0,0 +1,370 @@
+# Listagem
+
+O componente padrão para listar registros se chama `DataSet`.
+
+Ele apresenta os registros da página atual em uma grade responsiva de cartões, montada com os componentes de [layout](./layout.md) `Row` e `Column`. Cada registro ocupa a sua própria coluna e é apresentado por meio do slot padrão, que recebe o registro original (`item`) e a sua posição na página atual (`index`). Dentro do slot, monte o cartão de cada registro com o componente [`DataSetItem`](#componente-datasetitem), baseado no [agrupador de conteúdo](./section.md).
+
+## Propriedades
+
+### Itens
+
+A prop `items` define os registros a serem listados.
+
+```vue
+<template>
+  <u-data-set :items="pacientes">
+    <template #default="{ item }">
+      <u-data-set-item :title="item.nome" :subtitle="`Plano ${item.plano}`" />
+    </template>
+  </u-data-set>
+</template>
+
+<script lang="ts" setup>
+import { UDataSet, UDataSetItem } from "@nexdom/uimed-vue/components";
+
+const pacientes = [
+  { id: 1, nome: "Ana Souza", plano: "Ouro" },
+  { id: 2, nome: "Bruno Lima", plano: "Prata" },
+  { id: 3, nome: "Carla Dias", plano: "Bronze" },
+];
+</script>
+```
+
+### Colunas
+
+A prop `columns` define a quantidade máxima de registros apresentados lado a lado em cada linha da grade: `1`, `2`, `3`, `4` ou `6`. O padrão é `3`.
+
+A grade é responsiva e se adapta ao espaço que a listagem realmente ocupa, e não apenas ao tamanho da tela: para que cada cartão tenha pelo menos 240px de largura, a quantidade de registros por linha é reduzida para o maior dos valores acima que caiba na largura disponível. Assim, uma listagem dentro de um espaço estreito, como um diálogo ou um painel lateral, apresenta menos registros por linha, podendo chegar a um único registro. Em telas muito pequenas, como as de celulares, cada registro ocupa a largura inteira.
+
+Experimente alterar a quantidade de colunas no [Playground](#playground), cuja área de visualização é estreita, e a largura da janela: a quantidade de registros por linha se ajusta ao espaço disponível.
+
+```vue
+<template>
+  <u-data-set :items="pacientes" :columns="2">
+    <template #default="{ item }">
+      <u-data-set-item :title="item.nome" :subtitle="`Plano ${item.plano}`" />
+    </template>
+  </u-data-set>
+</template>
+
+<script lang="ts" setup>
+import { UDataSet, UDataSetItem } from "@nexdom/uimed-vue/components";
+
+const pacientes = [
+  { id: 1, nome: "Ana Souza", plano: "Ouro" },
+  { id: 2, nome: "Bruno Lima", plano: "Prata" },
+  { id: 3, nome: "Carla Dias", plano: "Bronze" },
+  { id: 4, nome: "Daniel Rocha", plano: "Ouro" },
+];
+</script>
+```
+
+### Paginação
+
+Os registros são divididos em páginas de acordo com a prop `itemsPerPage`, que por padrão apresenta até `10` registros por página. Os controles de paginação só são exibidos quando há mais de uma página.
+
+A página atual pode ser acompanhada, ou alterada, por meio do `v-model:page`, que inicia na primeira página.
+
+```vue
+<template>
+  <u-data-set v-model:page="paginaAtual" :items="consultas" :items-per-page="6">
+    <template #default="{ item }">
+      <u-data-set-item :title="item.paciente" :subtitle="item.especialidade">
+        Consulta em {{ item.data }}
+      </u-data-set-item>
+    </template>
+  </u-data-set>
+  Página atual: {{ paginaAtual }}
+</template>
+
+<script lang="ts" setup>
+import { ref } from "vue";
+import { UDataSet, UDataSetItem } from "@nexdom/uimed-vue/components";
+
+const paginaAtual = ref(1);
+const consultas = [
+  { id: 1, paciente: "Ana Souza", especialidade: "Cardiologia", data: "01/10/2026" },
+  { id: 2, paciente: "Bruno Lima", especialidade: "Dermatologia", data: "02/10/2026" },
+  // ...
+];
+</script>
+```
+
+### Pesquisa
+
+A prop `searchable` exibe um campo de pesquisa na barra acima dos registros, alinhado à direita e com 240px de largura, a mesma largura mínima de um cartão. Em telas muito pequenas, como as de celulares, ele ocupa a largura inteira. Apenas os registros que contêm o texto pesquisado, sem diferenciar maiúsculas e minúsculas, são listados, e a listagem volta para a primeira página a cada nova pesquisa.
+
+Por padrão, todas as propriedades dos registros são consideradas. Utilize a prop `searchKeys` para restringir a pesquisa a algumas delas.
+
+O texto pesquisado pode ser acompanhado, ou alterado, por meio do `v-model:search`. Ele filtra os registros mesmo quando o campo de pesquisa não é exibido.
+
+```vue
+<template>
+  <u-data-set
+    v-model:search="pesquisa"
+    :items="pacientes"
+    :search-keys="['nome']"
+    :items-per-page="4"
+    :columns="2"
+    searchable
+  >
+    <template #default="{ item }">
+      <u-data-set-item :title="item.nome" :subtitle="`Plano ${item.plano}`" />
+    </template>
+  </u-data-set>
+  Pesquisa: {{ pesquisa }}
+</template>
+
+<script lang="ts" setup>
+import { ref } from "vue";
+import { UDataSet, UDataSetItem } from "@nexdom/uimed-vue/components";
+
+const pesquisa = ref("");
+const pacientes = [
+  { id: 1, nome: "Ana Souza", plano: "Ouro" },
+  { id: 2, nome: "Bruno Lima", plano: "Prata" },
+  // ...
+];
+</script>
+```
+
+### Ações da listagem
+
+A prop `actions` define as ações sobre a listagem como um todo, como "Novo paciente". Elas são exibidas como botões à esquerda da barra acima dos registros, na mesma linha do campo de pesquisa, e aceitam as mesmas opções das [ações do agrupador de conteúdo](./section.md#acoes). A barra só é exibida quando há ações ou pesquisa.
+
+Sem `variant`, as ações da listagem são `secondary`, e não `primary` como nas ações do agrupador de conteúdo e dos registros, para não concorrerem com elas. Uma ação que informa `variant` mantém a sua.
+
+Com o campo de pesquisa, as ações ocupam a metade esquerda da barra, e o campo, a metade direita. As ações que não cabem na metade delas passam para a linha seguinte, ainda à esquerda. Quando a listagem não tem largura para dois cartões lado a lado, como em diálogos e painéis laterais, as ações e o campo de pesquisa ficam em linhas separadas, com o campo ainda à direita. Em telas muito pequenas, como as de celulares, cada ação e o campo de pesquisa ocupam uma linha inteira.
+
+```vue
+<template>
+  <u-data-set
+    :items="pacientes"
+    :columns="2"
+    :actions="[
+      { label: 'Novo paciente', onClick: novoPaciente },
+      { label: 'Exportar', onClick: exportar },
+    ]"
+    searchable
+  >
+    <template #default="{ item }">
+      <u-data-set-item :title="item.nome" :subtitle="`Plano ${item.plano}`" />
+    </template>
+  </u-data-set>
+  Última ação: {{ ultimaAcao }}
+</template>
+
+<script lang="ts" setup>
+import { ref } from "vue";
+import { UDataSet, UDataSetItem } from "@nexdom/uimed-vue/components";
+
+const ultimaAcao = ref("nenhuma");
+const pacientes = [
+  { id: 1, nome: "Ana Souza", plano: "Ouro" },
+  { id: 2, nome: "Bruno Lima", plano: "Prata" },
+  // ...
+];
+
+function novoPaciente() {
+  ultimaAcao.value = "Novo paciente";
+}
+
+function exportar() {
+  ultimaAcao.value = "Exportar";
+}
+</script>
+```
+
+### Sem registros
+
+Quando não há registros para listar, seja porque `items` está vazio ou porque nenhum registro corresponde à pesquisa, a mensagem "Nenhum registro encontrado." é exibida. Utilize a prop `noDataText` para personalizá-la.
+
+```vue
+<template>
+  <u-data-set :items="[]" no-data-text="Nenhum paciente agendado para hoje." />
+</template>
+
+<script lang="ts" setup>
+import { UDataSet } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+### Carregamento
+
+A prop `loading` exibe um skeleton loader no lugar da listagem enquanto uma operação está em andamento.
+
+```vue
+<template>
+  <u-data-set :items="pacientes" loading />
+</template>
+
+<script lang="ts" setup>
+import { UDataSet } from "@nexdom/uimed-vue/components";
+
+const pacientes = [
+  { id: 1, nome: "Ana Souza", plano: "Ouro" },
+  { id: 2, nome: "Bruno Lima", plano: "Prata" },
+];
+</script>
+```
+
+## Componente DataSetItem
+
+O componente `DataSetItem` apresenta um registro como um cartão, baseado no [agrupador de conteúdo](./section.md). Ele ocupa toda a altura da sua coluna, de forma que os cartões de uma mesma linha fiquem alinhados.
+
+### Título e subtítulo
+
+As props `title` e `subtitle` definem o título e uma breve descrição, exibidos no topo do cartão.
+
+```vue
+<template>
+  <u-data-set :items="pacientes" :columns="2">
+    <template #default="{ item, index }">
+      <u-data-set-item :title="`${index + 1}. ${item.nome}`" :subtitle="item.cidade" />
+    </template>
+  </u-data-set>
+</template>
+
+<script lang="ts" setup>
+import { UDataSet, UDataSetItem } from "@nexdom/uimed-vue/components";
+
+const pacientes = [
+  { id: 1, nome: "Ana Souza", cidade: "São Paulo - SP" },
+  { id: 2, nome: "Bruno Lima", cidade: "Belo Horizonte - MG" },
+];
+</script>
+```
+
+### Campos do registro
+
+O slot padrão do `DataSetItem` apresenta os detalhes do registro abaixo do título. Para apresentar alguns dos seus campos, utilize a [tabela](./table.md) com o layout `vertical`, que exibe o nome de cada campo ao lado do seu valor.
+
+```vue
+<template>
+  <u-data-set :items="pacientes" :columns="2">
+    <template #default="{ item }">
+      <u-data-set-item :title="item.nome" :subtitle="item.cidade">
+        <u-table
+          :headers="['Plano', 'Idade', 'Carteirinha']"
+          :items="[[item.plano, item.idade, item.carteirinha]]"
+          vertical
+        />
+      </u-data-set-item>
+    </template>
+  </u-data-set>
+</template>
+
+<script lang="ts" setup>
+import { UDataSet, UDataSetItem, UTable } from "@nexdom/uimed-vue/components";
+
+const pacientes = [
+  {
+    id: 1,
+    nome: "Ana Souza",
+    cidade: "São Paulo - SP",
+    plano: "Ouro",
+    idade: "34 anos",
+    carteirinha: "0001 2345 6789",
+  },
+  {
+    id: 2,
+    nome: "Bruno Lima",
+    cidade: "Belo Horizonte - MG",
+    plano: "Prata",
+    idade: "52 anos",
+    carteirinha: "0001 9876 5432",
+  },
+  // ...
+];
+</script>
+```
+
+### Ações
+
+A prop `actions` define as ações do registro, como "Editar" e "Excluir". Elas são exibidas como botões no rodapé do cartão, alinhadas entre os cartões de uma mesma linha mesmo quando os detalhes têm alturas diferentes, e aceitam as mesmas opções das [ações do agrupador de conteúdo](./section.md#acoes). Como as ações são definidas dentro do slot, cada uma pode usar o registro (`item`) diretamente.
+
+```vue
+<template>
+  <u-data-set :items="contatos" :columns="2">
+    <template #default="{ item }">
+      <u-data-set-item
+        :title="item.nome"
+        :subtitle="item.email"
+        :actions="[
+          { label: 'Editar', variant: 'secondary', onClick: () => editar(item) },
+          { label: 'Excluir', color: 'danger', variant: 'secondary', onClick: () => excluir(item) },
+        ]"
+      >
+        <u-table
+          :headers="Object.keys(item.telefones)"
+          :items="[Object.values(item.telefones)]"
+          vertical
+        />
+      </u-data-set-item>
+    </template>
+  </u-data-set>
+  Última ação: {{ ultimaAcao }}
+</template>
+
+<script lang="ts" setup>
+import { ref } from "vue";
+import { UDataSet, UDataSetItem, UTable } from "@nexdom/uimed-vue/components";
+
+type Contato = (typeof contatos)[number];
+
+const ultimaAcao = ref("nenhuma");
+const contatos = [
+  {
+    id: 1,
+    nome: "Ana Souza",
+    email: "ana.souza@example.com",
+    telefones: { Celular: "(00) 90000-0001", Residencial: "(00) 3000-0001" },
+  },
+  {
+    id: 2,
+    nome: "Bruno Lima",
+    email: "bruno.lima@example.com",
+    telefones: { Celular: "(00) 90000-0002" },
+  },
+];
+
+function editar(contato: Contato) {
+  ultimaAcao.value = `Editar ${contato.nome}`;
+}
+
+function excluir(contato: Contato) {
+  ultimaAcao.value = `Excluir ${contato.nome}`;
+}
+</script>
+```
+
+### Variantes
+
+A prop `variant` define a variação de estilo do cartão, assim como no agrupador de conteúdo: `primary` ou `secondary`. O padrão é `primary`.
+
+```vue
+<template>
+  <u-data-set :items="pacientes" :columns="2">
+    <template #default="{ item }">
+      <u-data-set-item :title="item.nome" :subtitle="`Plano ${item.plano}`" variant="secondary" />
+    </template>
+  </u-data-set>
+</template>
+
+<script lang="ts" setup>
+import { UDataSet, UDataSetItem } from "@nexdom/uimed-vue/components";
+
+const pacientes = [
+  { id: 1, nome: "Ana Souza", plano: "Ouro" },
+  { id: 2, nome: "Bruno Lima", plano: "Prata" },
+];
+</script>
+```
+
+## Playground
+
+Experimente as combinações de props do componente.
+
+## Ver também
+
+Consulte a referência de [API do UDataSet](../../api/components/data-sets/data-set.md) e da [API do UDataSetItem](../../api/components/data-sets/data-set-item.md) para a lista completa de props, slots e eventos.

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

@@ -0,0 +1,202 @@
+# Campos de data e hora
+
+O componente para campos de data e hora se chama `DateTimeField`.
+
+Ao clicar no campo, um seletor é aberto para escolher a data, o horário ou ambos. O valor é exibido no formato brasileiro (`24/09/2026`, `14:30` ou `24/09/2026 14:30`), mas o `v-model` utiliza os formatos padrão dos campos nativos:
+
+| Tipo       | Formato do `v-model` | Exemplo            |
+| ---------- | -------------------- | ------------------ |
+| `date`     | `YYYY-MM-DD`         | `2026-09-24`       |
+| `time`     | `HH:mm` (24 horas)   | `14:30`            |
+| `datetime` | `YYYY-MM-DDTHH:mm`   | `2026-09-24T14:30` |
+
+Quando não há valor, o `v-model` é uma `string` vazia (`""`).
+
+> [!Warning]
+> Deve ser utilizado no lugar do `<input>` nativo dos tipos `date`, `time` e `datetime-local`.
+
+## Propriedades
+
+### Tipos
+
+A prop `type` define quais seletores são apresentados e o formato do valor. O padrão é `datetime`.
+
+```vue
+<template>
+  <u-date-time-field v-model="dateValue" label="Data" type="date" />
+  <u-date-time-field v-model="timeValue" label="Horário" type="time" />
+  <u-date-time-field v-model="dateTimeValue" label="Data e hora" type="datetime" />
+</template>
+
+<script lang="ts" setup>
+import { ref } from "vue";
+import { UDateTimeField } from "@nexdom/uimed-vue/components";
+
+const dateValue = ref("2026-09-10");
+const timeValue = ref("08:00");
+const dateTimeValue = ref("2026-09-10T08:00");
+</script>
+```
+
+O seletor é fechado assim que o valor estiver completo:
+
+- `date`: ao escolher o dia;
+- `time`: ao escolher os minutos;
+- `datetime`: ao escolher o dia ou os minutos, desde que data e horário já estejam definidos.
+
+> [!Tip]
+> No tipo `datetime`, o `v-model` só é atualizado quando data e horário estão definidos. Ao escolher uma nova data, o horário atual é mantido. Se o seletor for fechado com apenas uma das partes escolhida, a seleção incompleta é descartada.
+
+### Variantes
+
+A prop `variant` define a variação de estilo aplicada ao campo. O padrão é `primary`.
+
+```vue
+<template>
+  <u-date-time-field label="Primary" variant="primary" />
+  <u-date-time-field label="Secondary" variant="secondary" />
+</template>
+
+<script lang="ts" setup>
+import { UDateTimeField } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+### Labels, placeholders e mensagens
+
+As props `label`, `placeholder` e `hint` funcionam da mesma forma que nos [campos de texto](./text-field.md).
+
+```vue
+<template>
+  <u-date-time-field
+    label="Data de nascimento"
+    type="date"
+    placeholder="dd/mm/aaaa"
+    hint="Informe a data do documento"
+  />
+</template>
+
+<script lang="ts" setup>
+import { UDateTimeField } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+### Limites
+
+As props `min` e `max` recebem valores no mesmo formato do `v-model` para o `type` atual. Opções fora do intervalo não podem ser escolhidas no seletor e, se o valor estiver fora do intervalo (por exemplo, quando definido pelo código), uma mensagem de erro é exibida.
+
+```vue
+<template>
+  <u-date-time-field
+    v-model="limitedValue"
+    label="Data do retorno"
+    type="date"
+    min="2026-09-10"
+    max="2026-09-20"
+    hint="Entre 10/09/2026 e 20/09/2026"
+  />
+  <u-button variant="secondary" @click="limitedValue = '2026-09-25'">Definir 25/09/2026</u-button>
+</template>
+
+<script lang="ts" setup>
+import { ref } from "vue";
+import { UButton, UDateTimeField } from "@nexdom/uimed-vue/components";
+
+const limitedValue = ref("2026-09-15");
+</script>
+```
+
+> [!Tip]
+> No tipo `datetime`, a data do limite restringe o calendário, e o horário do limite só restringe o relógio quando a data escolhida é a própria data do limite. Por exemplo, com `min="2026-09-10T08:00"`, os horários antes das 08:00 só ficam indisponíveis no dia 10/09/2026.
+
+### Obrigatório
+
+A prop `required` impede o envio do [formulário](./form.md) enquanto o campo estiver vazio.
+
+```vue
+<template>
+  <u-form>
+    <u-date-time-field label="Data da consulta" type="date" required />
+    <u-button type="submit">Enviar</u-button>
+  </u-form>
+</template>
+
+<script lang="ts" setup>
+import { UButton, UDateTimeField, UForm } 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-date-time-field label="Desabilitado" disabled />
+</template>
+
+<script lang="ts" setup>
+import { UDateTimeField } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+#### Somente leitura
+
+Utilize a prop `readonly` para evitar que o valor presente em um campo seja alterado. O seletor não é aberto.
+
+```vue
+<template>
+  <u-date-time-field model-value="2026-09-24T14:30" label="Somente leitura" readonly />
+</template>
+
+<script lang="ts" setup>
+import { UDateTimeField } 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-date-time-field label="Carregando" loading />
+</template>
+
+<script lang="ts" setup>
+import { UDateTimeField } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+#### Limpável
+
+A prop `clearable` exibe um recurso para limpar o campo, que altera o `v-model` para uma `string` vazia. O recurso não é exibido enquanto o campo estiver somente leitura.
+
+```vue
+<template>
+  <u-date-time-field v-model="clearableValue" label="Limpável" type="date" clearable />
+</template>
+
+<script lang="ts" setup>
+import { ref } from "vue";
+import { UDateTimeField } from "@nexdom/uimed-vue/components";
+
+const clearableValue = ref("2026-09-24");
+</script>
+```
+
+## Eventos
+
+### Atualização
+
+O evento `update:modelValue` será emitido toda vez que o usuário escolher um valor completo ou limpar o campo, repassando o novo valor como uma `string`.
+
+## Playground
+
+Experimente as combinações de props do componente.
+
+## Ver também
+
+Consulte a referência de [API do UDateTimeField](../../api/components/date-time-field.md) para a lista completa de props, slots e eventos.

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

@@ -0,0 +1,76 @@
+# Conteúdo Expansível
+
+O componente padrão para exibir conteúdo que pode ser expandido e recolhido se chama `Details`.
+
+> [!Warning]
+> Deve ser utilizado no lugar do `<details>` nativo.
+
+O conteúdo inicia recolhido e é exibido ao clicar no título.
+
+## Propriedades
+
+### Variantes
+
+A prop `variant` define a variação de estilo aplicada ao conteúdo expansível. O padrão é `primary`.
+
+```vue
+<template>
+  <u-details variant="primary" title="Primary">Conteúdo expansível primary</u-details>
+  <u-details variant="secondary" title="Secondary">Conteúdo expansível secondary</u-details>
+</template>
+
+<script lang="ts" setup>
+import { UDetails } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+### Título
+
+A prop `title` define o texto exibido no cabeçalho. Ao clicar nele, o conteúdo é expandido ou recolhido.
+
+```vue
+<template>
+  <u-details title="Mais informações">Conteúdo exibido ao expandir</u-details>
+</template>
+
+<script lang="ts" setup>
+import { UDetails } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+### Carregamento
+
+A prop `loading` exibe um skeleton loader no lugar do conteúdo expansível enquanto uma operação está em andamento.
+
+```vue
+<template>
+  <u-details title="Carregando..." loading>Conteúdo expansível</u-details>
+</template>
+
+<script lang="ts" setup>
+import { UDetails } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+### Vários conteúdos expansíveis
+
+Cada `Details` é independente: vários podem ficar abertos ao mesmo tempo.
+
+```vue
+<template>
+  <u-details title="Primeiro">Conteúdo do primeiro</u-details>
+  <u-details title="Segundo">Conteúdo do segundo</u-details>
+</template>
+
+<script lang="ts" setup>
+import { UDetails } 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 UDetails](../../api/components/details.md) para a lista completa de props e slots.