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

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

@@ -0,0 +1,51 @@
+# O que é UIMed-Vue?
+
+É um framework de UI, para [Vuejs](https://vuejs.org/), com diversos componentes e funções reutilizáveis entre eles (_components_ e _composables_).
+
+> [!Danger]
+> Construído para atender um design system específico e, portanto, eliminando a necessidade de qualquer esforço para sua estilização.
+>
+> Portanto, evite o uso de CSS ou estilizações paralelas enquanto estiver trabalhando com este framework.
+
+## Casos de uso
+
+### Componentes
+
+São recursos que permitem a elaboração e reutilização de interface gráfica.
+
+Os componentes a seguir possuem exemplos práticos de utilização dentro desta documentação.
+
+| Recurso                                                                | Descrição                                              |
+| ---------------------------------------------------------------------- | ------------------------------------------------------ |
+| [Botões](./components/button.md)                                          | Componente de botão.                                   |
+| [Botões de ícone](./components/icon-button.md)                            | Componente de botão que exibe apenas um ícone.         |
+| [Campos com máscara](./components/mask-field.md)                          | Componente para campo de texto com máscara.            |
+| [Campos com preenchimento automático](./components/autocomplete-field.md) | Componente para autocomplete/combobox.                 |
+| [Caixas de seleção](./components/checkbox.md)                             | Componente para caixa de seleção.                      |
+| [Campos de data e hora](./components/date-time-field.md)                  | Componente para campo de data e/ou hora.               |
+| [Campos de texto](./components/text-field.md)                             | Componente para campo de texto.                        |
+| [Componente base](./components/main.md)                                   | Componente raiz.                                       |
+| [Componentes de layout](./components/layout.md)                           | Componentes para seguir o grid system.                 |
+| [Agrupador de Conteúdo](./components/section.md)                          | Componente para agrupar conteúdo.                      |
+| [Conteúdo Expansível](./components/details.md)                            | Componente para expandir e recolher conteúdo.          |
+| [Formulários](./components/form.md)                                       | Componente de formulário.                              |
+| [Imagens](./components/img.md)                                            | Componente para apresentação de imagens.               |
+| [Janelas modais](./components/dialog.md)                                  | Componente para apresentar conteúdo em janelas modais. |
+| [Links](./components/link.md)                                             | Componente para links de texto.                        |
+| [Listagens](./components/data-set.md)                                     | Componente para listagem de dados.                     |
+| [Tabelas](./components/table.md)                                          | Componente para apresentação de dados em tabelas.      |
+| [Transição de páginas](./components/page-transition.md)                   | Componente para animar a troca de páginas.             |
+
+### Composables
+
+São funções que possibilitam a reutilização de recursos entre diversos componentes.
+
+As composables a seguir possuem exemplos práticos de utilização dentro desta documentação.
+
+| Recurso                                                    | Descrição                                                                          |
+| ---------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| [Toasts](./composables/use-toast.md)                          | Composables para apresentar mensagens `toast`.                                     |
+| [RunOrToast](./composables/use-run-or-toast.md)               | Composables para executar métodos e apresentar mensagens `toast` em caso de falha. |
+| [Diálogos](./composables/use-dialog.md)                       | Composables para apresentar diálogos.                                              |
+| [Confirmações](./composables/use-confirm.md)                  | Composables para executar ações após a confirmação do usuário.                     |
+| [Alterações não salvas](./composables/use-unsaved-changes.md) | Composables para evitar a perda de alterações não salvas ao sair da página.        |

package/skills/uimed-vue/references/guide/migration-v1-to-v2.md

@@ -0,0 +1,191 @@
+# Migrando da v1 para v2
+
+A versão 2 do UIMed-Vue introduz uma mudança significativa: todos os componentes exportados agora possuem um prefixo `U`, padronizando a forma como você importa e utiliza os componentes. Além disso, alguns componentes receberam nomes mais descritivos internamente.
+
+## Mapa de Renomeação
+
+| Nome anterior | Novo nome         |
+| ------------- | ----------------- |
+| `Btn`         | `UButton`         |
+| `Frm`         | `UForm`           |
+| `Root`        | `UMain`           |
+| `ContentSet`  | `USection`        |
+| `Content`     | `USectionContent` |
+| `Container`   | `UContainer`      |
+| `Row`         | `URow`            |
+| `Column`      | `UColumn`         |
+| `TextField`   | `UTextField`      |
+
+## Antes e Depois
+
+### Importações
+
+**Antes (v1):**
+
+```js
+import { Root, Btn, Row, Column, TextField } from "@nexdom/uimed-vue/components";
+```
+
+**Depois (v2):**
+
+```js
+import { UMain, UButton, URow, UColumn, UTextField } from "@nexdom/uimed-vue/components";
+```
+
+### Template
+
+**Antes (v1):**
+
+```vue
+<template>
+  <root>
+    <row>
+      <column>
+        <btn @click="handleClick">Clique aqui</btn>
+      </column>
+    </row>
+  </root>
+</template>
+```
+
+**Depois (v2):**
+
+```vue
+<template>
+  <u-main>
+    <u-row>
+      <u-column>
+        <u-button @click="handleClick">Clique aqui</u-button>
+      </u-column>
+    </u-row>
+  </u-main>
+</template>
+```
+
+### Notificações do menu superior
+
+A propriedade `date` das notificações do menu superior (`appBar.notifications`) foi substituída por `when`, um texto livre apresentado exatamente como informado. Assim, a aplicação passa a decidir como indicar quando a notificação foi gerada (exemplo: `"10:30"`, `"Ontem"` ou `"Há 5 minutos"`).
+
+**Antes (v1):**
+
+```ts
+const appBar = {
+  title: "Minha aplicação",
+  notifications: [{ title: "Nova versão", date: new Date() }],
+};
+```
+
+**Depois (v2):**
+
+```ts
+const appBar = {
+  title: "Minha aplicação",
+  notifications: [{ title: "Nova versão", when: "10:30" }],
+};
+```
+
+Para manter a formatação apresentada na v1 (horário para notificações de hoje, "Ontem" para as de ontem e a data completa para as demais), utilize as funções de [`@nexdom/shared`](https://nexdom-healthtech.github.io/shared/):
+
+```ts
+import { formatDateTime, toPeriodInterval } from "@nexdom/shared/utils";
+
+function formatNotificationWhen(date: Date) {
+  const interval = toPeriodInterval(date);
+  const wasThisMonth = interval.months === 0 && interval.years === 0;
+
+  if (wasThisMonth && interval.days === 0) return formatDateTime(date, "HH:mm");
+  if (wasThisMonth && interval.days === 1) return "Ontem";
+
+  return formatDateTime(date, "DD/MM/YYYY");
+}
+
+const appBar = {
+  title: "Minha aplicação",
+  notifications: [{ title: "Nova versão", when: formatNotificationWhen(new Date()) }],
+};
+```
+
+### Alinhamento vertical das colunas
+
+Na v1, as colunas de uma `Row` eram esticadas até a altura da coluna mais alta da linha. Na v2, a prop `alignY` da `URow` controla esse alinhamento e o padrão passou a ser `"start"`: cada coluna mantém a altura do próprio conteúdo e fica alinhada ao topo. Para manter o comportamento da v1, como em cartões lado a lado que devem ter a mesma altura, utilize `align-y="stretch"` (veja [Alinhamento vertical das colunas](./components/layout.md#alinhamento-vertical-das-colunas)).
+
+**Antes (v1):**
+
+```vue
+<template>
+  <row>
+    <column cols="6">
+      <content-set title="Consultas" full-height>
+        <!-- conteúdo curto -->
+      </content-set>
+    </column>
+    <column cols="6">
+      <content-set title="Exames" full-height>
+        <!-- conteúdo mais longo -->
+      </content-set>
+    </column>
+  </row>
+</template>
+```
+
+**Depois (v2):**
+
+```vue
+<template>
+  <u-row align-y="stretch">
+    <u-column cols="6">
+      <u-section title="Consultas" full-height>
+        <!-- conteúdo curto -->
+      </u-section>
+    </u-column>
+    <u-column cols="6">
+      <u-section title="Exames" full-height>
+        <!-- conteúdo mais longo -->
+      </u-section>
+    </u-column>
+  </u-row>
+</template>
+```
+
+### Menu de navegação
+
+Na v2, o ícone (`icon`) é obrigatório nos itens e grupos do primeiro nível do menu de navegação (`navigationMenu`). Os itens dentro de um grupo continuam sem ícone. Os nomes disponíveis estão em [Ícones](./icons.md).
+
+Em telas a partir de 1145px, o menu deixa de ser aberto pelo botão "Menu de navegação" do menu superior, que não é mais exibido: ele fica sempre visível à esquerda do conteúdo, recolhido em uma faixa de 56px com os ícones, e se expande sobre o conteúdo com o mouse, com o foco do teclado ou pelo atalho `Ctrl + K` (veja [Menu de navegação](./components/main.md#menu-de-navegacao)). O conteúdo da página fica 56px mais estreito, e testes automatizados que clicavam no botão para abrir o menu passam a encontrá-lo apenas em telas menores. Em telas menores, o menu continua sendo aberto pelo botão.
+
+**Antes (v1):**
+
+```ts
+const navigationMenu = {
+  items: [
+    { description: "Início", route: "/" },
+    { description: "Cadastros", items: [{ description: "Pacientes", route: "/pacientes" }] },
+  ],
+};
+```
+
+**Depois (v2):**
+
+```ts
+const navigationMenu = {
+  items: [
+    { description: "Início", route: "/", icon: "home" },
+    {
+      description: "Cadastros",
+      icon: "folder",
+      items: [{ description: "Pacientes", route: "/pacientes" }],
+    },
+  ],
+};
+```
+
+## Dicas de Migração
+
+1. Procure por todas as importações antigas e substitua pelos novos nomes com o prefixo `U`
+2. Atualize todos os templates para usar as novas tags em kebab-case (ex: `<u-button>` em vez de `<btn>`)
+3. Os tipos de props não são mais exportados pela biblioteca. Utilize `ComponentProps`, de [`vue-component-type-helpers`](https://www.npmjs.com/package/vue-component-type-helpers), para obtê-los a partir do componente (veja [Tipagem de props](./getting-started.md#tipagem-de-props))
+4. Substitua a propriedade `date` das notificações do menu superior por `when`, informando o texto já formatado (veja [Notificações do menu superior](#notificacoes-do-menu-superior))
+5. Adicione `align-y="stretch"` às `URow` cujas colunas precisam ter a mesma altura (veja [Alinhamento vertical das colunas](#alinhamento-vertical-das-colunas))
+6. Informe um `icon` em todos os itens e grupos do primeiro nível do menu de navegação, e revise as telas e os testes que contavam com o botão do menu em telas largas (veja [Menu de navegação](#menu-de-navegacao))
+
+Para mais informações sobre cada componente, consulte a [Documentação da API](../api/index.md).

package/skills/uimed-vue/references/guide/unit-testing.md

@@ -0,0 +1,85 @@
+# Testes Unitários
+
+Testes unitários com o UIMed-Vue são muito simples, pois este framework já vem com plugins que atendem as ferramentas que serão listadas a seguir.
+
+## Usando Vitest
+
+Para realizar as configurações, atualize seu arquivo `vite.config.ts` da seguinte maneira:
+
+```ts [vite.config.ts]
+import { defineConfig } from "vite";
+import { vitestServerPluginUimed } from "@nexdom/uimed-vue/plugins"; // [!code ++]
+
+export default defineConfig({
+  test: {
+    server: vitestServerPluginUimed(), // [!code ++]
+  },
+});
+```
+
+## Escrevendo os testes
+
+Uma vez que as etapas mencionadas anteriormente foram realizadas, utilize o recurso de testes unitários do uimed-vue para montar os seus componentes `wrapper` através do [`@vue/test-utils`](https://test-utils.vuejs.org/).
+
+```ts [hello-world.test.ts]
+import { mount } from "@vue/test-utils";
+import { vueTestUtilsPluginUimed } from "@nexdom/uimed-vue/unit-test"; // [!code ++]
+import HelloWorld from "../hello-world.vue";
+
+describe("HelloWorld", () => {
+  it("displays message", () => {
+    const wrapper = mount(HelloWorld, {
+      global: {
+        plugins: [vueTestUtilsPluginUimed()], // [!code ++]
+      },
+    });
+
+    // Verifica se o wrapper/componente contém o texto esperado.
+    expect(wrapper.text()).toContain("Olá, Mundo!");
+  });
+});
+```
+
+O plugin de testes usa o mesmo idioma do `createUimed()`, então os testes veem os mesmos textos em português da aplicação, como os anúncios para leitores de tela e os rótulos da paginação.
+
+## Testando código que usa diálogos
+
+Os diálogos das composables [`useDialog`](./composables/use-dialog.md) e [`useConfirm`](./composables/use-confirm.md) são exibidos pelo [Componente base](./components/main.md). Em um teste que monta apenas o seu componente, sem o `UMain`, nenhum diálogo é exibido e a `Promise` de `dialog` ou `confirm` não é resolvida.
+
+Nos testes unitários, substitua as composables por versões simuladas que respondem pelo usuário:
+
+```ts [delete-patient.test.ts]
+import { mount } from "@vue/test-utils";
+import { computed } from "vue";
+import { vueTestUtilsPluginUimed } from "@nexdom/uimed-vue/unit-test";
+import DeletePatient from "../delete-patient.vue";
+
+vi.mock(import("@nexdom/uimed-vue/composables"), async (importOriginal) => ({
+  ...(await importOriginal()),
+  // Simula o usuário confirmando: executa a ação como o `confirm` faria
+  useConfirm: () => ({
+    confirm: vi.fn((_options, action, ...params) => action(...params)),
+    isRunning: computed(() => false),
+  }),
+  // Simula o usuário escolhendo a ação de valor "stay"
+  useDialog: () => ({ dialog: vi.fn().mockResolvedValue("stay") }),
+}));
+
+describe("DeletePatient", () => {
+  it("deletes the patient once confirmed", async () => {
+    const wrapper = mount(DeletePatient, {
+      global: {
+        plugins: [vueTestUtilsPluginUimed()],
+      },
+    });
+
+    await wrapper.find("button").trigger("click");
+
+    // Verifique aqui o efeito da ação confirmada.
+  });
+});
+```
+
+Para simular um cancelamento, faça o `confirm` simulado resolver `false` sem executar a ação, e o `dialog` simulado resolver `undefined`.
+
+Para verificar o diálogo em si, prefira testes E2E, que exercitam a aplicação completa, com o `UMain` montado.

package/AGENTS.md

@@ -1,160 +0,0 @@
-# AGENTS.md
-
-## Project
-
-`@nexdom/uimed-vue` is a Vue 3 UI component library for NEXDOM applications, built on top of [Vuetify](https://vuetifyjs.com/) and [Material Design 3](https://m3.material.io/). It's published to npm and documented via VitePress at https://nexdom-healthtech.github.io/uimed-vue/.
-
-Tooling is built around [Vite+](https://github.com/voidzero-dev/vite-plus) (`vp`/`vpr`/`vpx` CLIs), not raw `vite`/`vitest`/`eslint` invocations.
-
-## Using this library in an app
-
-These steps are for developers _consuming_ `@nexdom/uimed-vue` in a Vue application (not for contributing to this repo — see the rest of this document for that).
-
-### Install
-
-```bash
-vp add @nexdom/uimed-vue
-# But, if you're not using Vite+ yet...
-npm i @nexdom/uimed-vue
-# Or
-pnpm add @nexdom/uimed-vue
-# Or
-yarn add @nexdom/uimed-vue
-```
-
-Peer dependencies (`@fontsource/roboto`, `@mdi/font`, `@nexdom/shared`, `resize-observer-polyfill`, `vite-plugin-vuetify`, `vite-plus`, `vue`, `vue-router`, `vuetify`) must be installed alongside it — most package managers install these automatically, but confirm versions match what's declared in `package.json`'s `peerDependencies`.
-
-### Setup
-
-Add the Vite plugin:
-
-```ts
-// vite.config.ts
-import { vitePluginUimed } from "@nexdom/uimed-vue/plugins.ts";
-
-// ...
-
-plugins: [vue(), vitePluginUimed()];
-
-// ...
-```
-
-Register the plugin in the Vue app:
-
-```ts
-// main.js or main.ts
-import { createApp } from "vue";
-import { createUimed } from "@nexdom/uimed-vue";
-
-import App from "./App.vue";
-
-const uimed = createUimed();
-
-createApp(App).use(uimed).mount("#app");
-```
-
-### Usage
-
-Place the `Root` component at the top of `App.vue`, then add other components as needed:
-
-```vue
-<!-- App.vue -->
-<template>
-  <root>
-    <!-- ... -->
-  </root>
-</template>
-
-<script setup lang="ts">
-import { Root } from "@nexdom/uimed-vue/components";
-</script>
-```
-
-Never write CSS, classes or any kind of styling. Always use component props.
-
-The library doesn't export prop types. Derive them with `ComponentProps` from `vue-component-type-helpers`:
-
-```ts
-import type { ComponentProps } from "vue-component-type-helpers";
-import { UMain, USection } from "@nexdom/uimed-vue/components";
-
-type MainProps = ComponentProps<typeof UMain>;
-type AppBar = NonNullable<MainProps["appBar"]>;
-type NavigationMenu = NonNullable<MainProps["navigationMenu"]>;
-type SectionAction = NonNullable<ComponentProps<typeof USection>["actions"]>[number];
-```
-
-Available entry points: `@nexdom/uimed-vue` (root), `@nexdom/uimed-vue/components`, `@nexdom/uimed-vue/composables`, `@nexdom/uimed-vue/plugins`, `@nexdom/uimed-vue/unit-test` (test helpers, e.g. `vueTestUtilsPluginUimed()` for mounting components with Vuetify in Vitest).
-
-Full component/composable reference lives in the [docs](https://nexdom-healthtech.github.io/uimed-vue/).
-
-## Contributing to this repo
-
-The sections below are for developers working _on_ this library itself.
-
-### Dev environment setup
-
-This project expects to be opened inside its devcontainer (VSCode). If commands below fail with missing shims/commands, run:
-
-```bash
-vp env doctor   # diagnose missing parts
-vp env setup    # create shims like vpr and vpx
-vp install      # install dependencies
-```
-
-## Commands
-
-- `vpr check` — lint, formatter, and type-check (requires `build`/`pack` to have run first for the type-check step)
-- `vp test --coverage` — unit tests with coverage (Vitest, jsdom, 100% coverage threshold enforced)
-- `vpr test:mutations` — mutation tests (Stryker; thresholds: high 100, low 95, break 95)
-- `vpr test:e2e` — E2E tests (Playwright, runs against the built docs preview site)
-- `vpr depcruise` — architecture/dependency rules (dependency-cruiser)
-- `vp pack` / `vpr build` — build the library
-- `vpr docs` / `vpr docs:dev` — run docs site (imports the lib from `dist`, not `src` — run `vpr dev` in a second terminal to keep `dist` updated while iterating)
-
-CI (`.github/workflows/ci.yml`) runs, in order: commitlint on PR commits, `vp pack`, `vpr check`, `vpr depcruise`, `vp test --coverage`, `vpr test:mutations`, `vpr test:e2e`. Match this locally before opening a PR.
-
-## Code conventions
-
-- All `src` code is written in English. `docs` content is written in Portuguese (aimed at Brazilian users), even though file/dir names stay in English.
-  - `docs` must not mention Vuetify
-  - A new component/composable must be listed in its guide page (`docs/guide/…`), its API page (`docs/api/…`), both sidebars in `docs/.vitepress/config.ts`, the guide index table (`docs/guide/index.md`) and the API index list (`docs/api/index.md`).
-- Never write CSS, classes or any kind of styling. Always use component props.
-- Path aliases: `@/*` → `src/*`, `@e2e/*` → `e2e/*`.
-- Every public component follows this pattern to block access to internals and give it an editor-hover description:
-
-  ```vue
-  <script lang="ts">
-  /**
-   * A short description of the component, shown when hovering it in the
-   * editor.
-   */
-  export default {
-    inheritAttrs: false,
-  };
-  </script>
-
-  <script setup lang="ts">
-  // component's implementation
-  </script>
-  ```
-
-- Component layout: `src/components/<name>/<name>.vue`, `types.ts` for prop/option types, `__tests__/<name>.test.ts` for unit tests. Composables follow the same shape under `src/composables/<name>/`.
-- Public components/composables/types are re-exported from `src/components/index.ts` and `src/composables/index.ts`.
-- Every publicly exported component must use the `U` prefix on its export identifier (e.g., `UButton`, `UMain`), while internal file names and component names remain unprefixed.
-- Use [JSDoc](https://jsdoc.app/about-getting-started) on every method/prop/type intended to be part of the public API — it's the primary documentation surface and supports markdown/code examples.
-- Known workarounds (see CONTRIBUTING.md before touching related config): `stryker-vue-ignorer` patches a Stryker/Vue macro-hoisting issue; `vue-tsc` is used for type-check instead of Vite+'s built-in one due to an oxlint/Vue support gap. Both are meant to be removed once their upstream issues are fixed — don't build further on top of them without checking if they're still needed.
-
-## Testing conventions
-
-- Unit tests use Vitest + `@vue/test-utils`, with `vueTestUtilsPluginUimed()` from `@/unit-test.ts` to mount a Vuetify instance.
-- Global unit test setup (`src/__tests__/setup.ts`) stubs `visualViewport`, uses fake timers, and silences `console.error/warn/log`.
-- Coverage threshold is 100%; mutation testing threshold is 100% (break at 100). Don't add code paths without covering tests.
-- E2E tests (Playwright, `e2e/`) run against the built docs preview (`http://localhost:4173/uimed-vue/`). Snapshots/screenshots live under `__snapshots__`/`__screenshot__` next to each spec.
-
-## Git workflow
-
-- Trunk-based development. `main` is the only long-lived branch (`beta`/`alpha` exist only for pre-release/prototype work — see CONTRIBUTING.md for when to use them). `main`, `beta`, `alpha` are all protected against direct pushes.
-- Short-lived branches are named after their intention (e.g. `fix-some-method-behavior`) and are deleted after merging back via PR.
-- Commit messages MUST follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) — enforced by commitlint in CI. Recent examples: `feat(components): ...`, `fix(composables): ...`, `test(e2e): ...`, `docs(root): ...`, `chore: ...`.
-- Releases are automated via `semantic-release` (conventional-commits preset) — don't hand-edit versions/changelogs.

package/CLAUDE.md

@@ -1 +0,0 @@
-@AGENTS.md

package/dist/types-BPXXtbmW.d.ts

@@ -1,5 +0,0 @@
-//#region src/composables/colors/types.d.ts
-type ColorVariant = "primary" | "secondary" | FeedbackColorVariant;
-type FeedbackColorVariant = "positive" | "informative" | "caution" | "danger";
-//#endregion
-export { FeedbackColorVariant as n, ColorVariant as t };

package/dist/use-toast-CACuYhK_.js

@@ -1,53 +0,0 @@
-import { computed, ref, toValue } from "vue";
-const colorToVuetifyColor = {
-	primary: "primary",
-	secondary: "secondary",
-	positive: "success",
-	informative: "info",
-	caution: "warning",
-	danger: "error"
-};
-//#endregion
-//#region src/composables/colors/use-vuetify-color.ts
-function useVuetifyColor(color) {
-	return computed(() => {
-		const colorValue = toValue(color);
-		return colorValue ? colorToVuetifyColor[colorValue] : colorToVuetifyColor.primary;
-	});
-}
-//#endregion
-//#region src/composables/dialogs/use-toast.ts
-const messages = ref([]);
-/**
-* Composable which returns a function to display toast messages.
-*
-* @example
-* ```ts
-* const { toast } = useToast();
-* toast({ message: "Hello, World!" });
-* ```
-*/
-function useToast() {
-	return { toast };
-}
-/**
-* Displays a toast message.
-* @param {ToastOptions} options - Options for the toast message.
-*
-* @example
-* ```ts
-* toast({ message: "Hello, World!" });
-* ```
-*/
-function toast(options) {
-	const text = options.message;
-	const color = useVuetifyColor(options.color ?? "informative");
-	const toastMessage = {
-		text,
-		color: color.value,
-		prependIcon: `$${color.value}`
-	};
-	messages.value.push(toastMessage);
-}
-//#endregion
-export { useToast as n, useVuetifyColor as r, messages as t };