@nexdom/uimed-vue 2.0.0-beta.63 → 2.0.0-beta.64

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,274 +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 (`@mdi/js`, `@nexdom/shared`, `resize-observer-polyfill`, `sass-embedded`, `vite-plus`, `vue`, `vue-component-type-helpers`, `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, which compiles the components' styles with the library's font and Sass settings. Without it, components lose the Unimed Slab font:
-
-```ts
-// vite.config.ts
-import { vitePluginUimed } from "@nexdom/uimed-vue/plugins";
-
-// ...
-
-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 `UMain` component at the top of `App.vue`, then add other components as needed:
-
-```vue
-<!-- App.vue -->
-<template>
-  <u-main>
-    <!-- ... -->
-  </u-main>
-</template>
-
-<script setup lang="ts">
-import { UMain } 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
-```
-
-On Windows, prefer VSCode's "Dev Containers: Clone Repository in Container Volume" over opening a folder cloned on the host:
-
-- A host clone with `core.autocrlf=true` checks files out with CRLF, and `vpr check` then reports formatting issues on every file. `.gitattributes` enforces LF, but clones made before it was added need `git rm -rq --cached . && git reset --hard` to be re-normalized (commit or stash local changes first, since `reset --hard` discards them).
-- A host folder bind-mounted into the container is roughly 10x slower (unit tests alone go from seconds to minutes), which makes Stryker's initial test run time out.
-
-## Commands
-
-- `vpr check` — lint, formatter, and type-check (builds the library first, since the type-check reads `dist`)
-- `vp test --coverage` — unit tests with coverage (Vitest, jsdom, 100% coverage threshold enforced)
-- `vpr test:mutations` — mutation tests (Stryker; thresholds: high 100, low 100, break 100). It starts one test runner per CPU core; on machines with limited memory, run `vpx stryker run --concurrency 4` instead
-- `vpr test:e2e` — E2E tests (Playwright, runs against the built docs preview site). Outside CI it reuses any server already on port 4173, which is also `vpr docs:dev`'s port: stop the dev server first, or the tests run against it instead of the built site. A running `vitepress preview` keeps serving the build it started with, so restart it after rebuilding the docs
-- `vpr depcruise` — architecture/dependency rules (dependency-cruiser)
-- `vp pack` / `vpr build` — build the library. It publishes one module per source file (`unbundle` in `vite.config.ts`), and the entry points import them instead of copying their code, so the apps' bundlers can split the components by the route that uses them
-- `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`, and then the SonarQube analysis (`vpr sonar`), whose quality gate fails the PR on any issue or unreviewed security hotspot in `src/` (see [Static analysis](#static-analysis-sonarqube)). Match this locally before opening a PR.
-
-### Focused runs while iterating
-
-The full suite takes minutes; while working on a single component or composable, scope each step to it (`button` below is an example) and run the full suite only before opening a PR:
-
-```bash
-# Unit tests of one or more folders
-vp test src/components/button
-
-# Same, with coverage limited to the files you changed. Without `--coverage.include`, files that
-# are only imported (e.g. the children of `main.vue`) count as uncovered and fail the 100% threshold
-vp test src/components/button --coverage --coverage.include="src/components/button/**"
-
-# Mutation tests of specific files. List several files in a single comma-separated `--mutate`
-# (repeating the flag keeps only the last one)
-vpx stryker run --mutate "src/components/button/button.vue,src/composables/button/button.ts"
-
-# One E2E spec
-vpr test:e2e e2e/components/button.spec.ts
-```
-
-### Static analysis (SonarQube)
-
-The company's SonarQube runs only in CI, after the E2E tests. Write code that avoids the rules that have already failed PRs here: use `globalThis` instead of `window`; move inner functions that don't use anything from the outer function out of it (S7721); don't use deprecated APIs (e.g. `event.returnValue`); don't write template comments that look like code; don't add non-null assertions or casts that don't change the type (S4325); no regular expressions with super-linear backtracking, such as two overlapping quantifiers (S5852); and prefer native elements to `role` attributes (S6819).
-
-Only if CI's SonarQube step fails and its dashboard doesn't show why, reproduce the analysis with a local SonarQube Community in the server's version (`sonarqube:26.3.0.120487-community`) and `vpx @sonar/scan` pointed at it. The goal is 0 issues and no new security hotspots in the files the PR changed.
-
-## Adding a new component
-
-Use an existing component (e.g. `button`) as the reference, and deliver all of the following in the same PR:
-
-1. `src/components/<name>/<name>.vue` (following the pattern in [Code conventions](#code-conventions)), `types.ts` and `__tests__/<name>.test.ts`.
-2. The `U`-prefixed export in `src/components/index.ts`.
-3. A usage guide at `docs/guide/components/<name>.md`, with `<demo>` examples (and a `<playground>` section when the component has configurable props), and an API reference at `docs/api/components/<name>.md` (props, events and slots tables). Both in Portuguese. In a demo's template inside a `.md` file, don't put an attribute with a template literal after one with an arrow function in the same tag: the Markdown type-check (`vue-tsc`) reads the `>` of `=>` as the end of the tag and fails with `TS1003`. Order the attributes so the template literal comes first.
-4. Both pages registered in the sidebar at `docs/.vitepress/config.ts`.
-5. `e2e/components/<name>.spec.ts` covering the guide's interactive examples, an "accessibility" check (see [Testing conventions](#testing-conventions)) and a "UI consistency" screenshot check (plus accessible snapshots where relevant). Commit the generated files under `__snapshots__`/`__screenshot__`.
-6. The full CI sequence passing locally.
-
-## Adding a new composable
-
-Use an existing composable (e.g. `use-toast`) as the reference, and deliver in the same PR:
-
-1. `src/composables/<group>/<name>.ts` and `__tests__/<name>.test.ts`, plus the types in the group's `types.ts`. If it relies on an internal component (as `useToast` relies on the internal `Toast` rendered by `UMain`), that component follows the component layout but isn't exported.
-2. The export in `src/composables/index.ts`, and its assertion in `src/composables/__tests__/index.test.ts`.
-3. A usage guide at `docs/guide/composables/<name>.md` and an API reference at `docs/api/composables/<name>.md`, both in Portuguese, registered in both sidebars at `docs/.vitepress/config.ts` and listed in `docs/api/index.md` and in the table of `docs/guide/index.md`. If it relies on `UMain` (like `useToast`), also mention it in `UMain`'s guide and API pages.
-4. `e2e/composables/<name>.spec.ts` covering the guide's examples, an "accessibility" check (see [Testing conventions](#testing-conventions)) and a "UI consistency" screenshot check.
-5. The full CI sequence passing locally.
-
-## 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 or `<style>` blocks, and expose styling to consumers only through props.
-- Adjustments that Vuetify exposes as Sass variables (e.g. a font family or a line height) go in `src/styles/settings.scss`, which `vitePluginUimed()` compiles into Vuetify's stylesheets in the apps. That file only configures variables: still no CSS rules.
-  - It also limits Vuetify's utility classes to the families the components use, without breakpoint and print variants, and its color classes to black, white and transparent, since the utility stylesheet blocks the apps' first render. Using a class from another family (e.g. `ga-2` or `overflow-hidden`) means enabling its key in `$utilities` there; the unit tests of `src/__tests__/plugins.test.ts` fail when a class used in `src` isn't generated. The theme's colors (`bg-primary`, `text-primary-text`, ...) don't depend on it.
-- Don't add spacing to Vuetify components: no padding or margin utility classes (`pa-*`, `pt-6`, `px-4`, `ma-2`, ...) and no spacing props overriding the defaults. Vuetify already applies Material Design 3 spacing, and overriding it breaks what it handles on its own, such as button paddings and the scrollbar of scrollable content. If the default spacing looks wrong, stop and ask instead of adjusting it. The one accepted layout margin is `mt-auto` on `v-card-actions` (as in `USection`), which pushes the actions to the bottom of a full-height card without setting any spacing value.
-- Prefer a Vuetify component's own props to building its parts by hand (e.g. `title`/`text` on `v-card` instead of `v-card-item` > `v-card-title` > `v-card-text`). A non-spacing utility class is acceptable only when no prop covers the need (e.g. `text-wrap` on a card title), with a comment saying why. Props covered by the shared composables below are the exception: they always go through them.
-- Reuse the shared internal composables for props that recur across components, so every component maps them to Vuetify the same way, instead of mapping them again:
-  - `fullWidth`/`fullHeight`: `useFullWidth`/`useFullHeight` (`src/composables/dimensions/dimensions.ts`), applying Vuetify's `w-100`/`h-100` classes even where the component has `width`/`height` props.
-  - `alignX`/`alignY`: `useAlignX`/`useAlignY` (`src/composables/alignment/alignment.ts`), with the `AlignX`/`AlignY` types from the group's `types.ts`.
-  - `color`: `useVuetifyColor` (`src/composables/colors/use-vuetify-color.ts`), with the `ColorVariant` type from the group's `types.ts`. Where the color is the text's instead of a fill (e.g. `UButton`'s `ghost` variant), use `useVuetifyTextColor` (`use-vuetify-text-color.ts`) instead: most fills are too light to reach WCAG AA's contrast as text, so each color has a text shade in the theme, darker than its fill (primary's fill is dark enough to be its own shade).
-
-  A new prop that does the same as one of these takes its name and type. When a second component needs a mapping that only one component has, move it into a shared composable first.
-
-- Keep components thin: a component wires props, slots and events to Vuetify. Logic beyond that (focus management, queues, DOM lookups, comparisons) goes into an internal composable with its own unit tests.
-- Path aliases: `@/*` → `src/*`, `@e2e/*` → `e2e/*`.
-- A prop or option that points to a navigation destination is typed `RouteLocationRaw` (from `vue-router`) and named `route` (e.g. the items of `UNavigationMenu`), unless the name says which destination it is (e.g. `help` in `UAppBar`). Don't split it into `to`/`href` props: convert it with `useRouteProps`/`routeToProps` (`src/composables/navigation/use-route-props.ts`), which binds strings starting with `http` as `href` and anything else as the router's `to`.
-- 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. Components that belong to a group live in the group's folder (e.g. the internal `src/components/dialogs/toast.vue`).
-- Composables live in a group folder: `src/composables/<group>/<name>.ts`, with `types.ts` and `__tests__/` in the group folder (e.g. `src/composables/dialogs/use-toast.ts`). A composable (`use-*.ts`) must depend on `vue` or `vue-router`, directly or through other modules (enforced by dependency-cruiser's `composables-use-vue` rule).
-- Library-wide configuration constants that aren't components or composables live in `src/consts/<name>.ts` (e.g. `src/consts/locale.ts`, the language set by `createUimed()` and `vueTestUtilsPluginUimed()`), with their types in `src/consts/types.ts`.
-- Icons are drawn as inline SVGs with the paths of `@mdi/js`, imported one by one so the apps' bundles only take the icons used: there's no icon font, so never use `mdi-*` classes. Every icon is in the internal `icons` map of `src/consts/icons.ts`, and every name in it is public (the `Icon` type in `src/consts/types.ts`):
-  - To add an icon, add it to that map and to the list on the "Ícones" guide page (`docs/guide/icons.md`), in the same order, and check that `@mdi/js` exports it: the unit test of `src/consts/icons.ts` checks every path, and the page's E2E spec fails when the page and the map list different icons. Names are camelCase, like the Vuetify aliases they must match (e.g. `checkboxOn`/`checkboxOff`). Reuse an existing name before adding one with the same drawing.
-  - Components use the map for their own icons too (`icons.help`, `icons.close`), never `$` aliases nor `mdi-*` strings.
-  - The map is also Vuetify's alias set (`createUimed()` and `vueTestUtilsPluginUimed()` pass it as `aliases`), since Vuetify's components draw some icons by alias on their own (e.g. `$clear` in clearable fields, `$prev`/`$next` in the pagination). It only has the aliases the library's components render, so a component that renders a new one (a new Vuetify component or prop) needs it added to the map, named exactly as the alias; without it, the icon is drawn empty, without a warning. Add each state that renders an alias to `src/consts/__tests__/icon-aliases.test.ts`, which fails on icons drawn without a path of `@mdi/js`.
-- Pure helpers that don't use Vue live in `src/utils/<name>.ts`, with tests in `src/utils/__tests__/`. Generic helpers that any TypeScript project could use (e.g. `isDeepEqual`) belong in `@nexdom/shared` instead.
-- No module in `src` has side effects at its top level (code that must run just because the module is imported, such as registering something globally), except the CSS imports of `src/index.ts`: `package.json` declares `"sideEffects": ["*.css"]`, so the apps' bundlers drop or move to another chunk any other module whose exports aren't used. A new side effect means adding its built file (e.g. `./dist/...`) to `sideEffects`.
-- Public components/composables are re-exported from `src/components/index.ts` and `src/composables/index.ts`. Prop types stay internal (`types.ts` is not re-exported); consumers derive them with `ComponentProps` (see [Usage](#usage)).
-- 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; the internal `SkeletonLoader` wraps Vuetify's skeleton loader so its loading announcement gets valid ARIA attributes in server rendering; the navigation menu's rail (`useNavigationRail`) dispatches synthetic `mouseenter`/`mouseleave` events on Vuetify's navigation drawer, which only expands its rail on mouse events, to expand it on keyboard focus and keep it expanded when the mouse leaves with the focus inside. All are meant to be removed once fixed upstream — 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`.
-- With fake timers in jsdom, Vuetify transitions (e.g. of `VDialog`, `VMenu`) don't finish on their own. Emit the transition events on the Vuetify component (`wrapper.findComponent(VDialog).vm.$emit("afterLeave")`) or advance the timers with `await vi.runAllTimersAsync()`.
-- Coverage threshold is 100%; mutation testing threshold is 100% (break at 100). Don't add code paths without covering tests. Mutants that don't compile are reported as compile errors and don't count toward the score.
-- 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.
-- Every E2E spec has an "accessibility" `describe` that calls `expectNoA11yViolations(page)` from `e2e/utils.ts` at least once. It runs axe against WCAG 2.2 AA and its best practices on the page's demos and overlays, in both of the docs' color schemes (the demos keep the library's light theme on a background of their own in dark mode), and fails on any violation. Check each state that renders something new, too: open overlays (menus, dialogs, toasts) and every color of a variant whose text takes the color (as `button.spec.ts` does for `ghost`). Contrast is the most common failure: the theme's colors and text shades must keep 4.5:1, which `src/__tests__/index.test.ts` checks. Don't make a check pass by disabling rules or excluding elements: fix the cause, or stop and ask. The helper only disables the landmark rules that fail because of the docs' layout, with a comment saying why.
-- Before keeping a new screenshot as a baseline, open it and check it against how plain Vuetify renders the same component: overflowing content shows its scrollbar, buttons and cards keep their native paddings, nothing touches the edges or gets clipped. A screenshot that only "looks fine" isn't enough: name what you checked in your report.
-- Generate and update screenshots only on Linux, as CI does: in the Dev Container, or in the Playwright Docker image of the version in `package.json` (`mcr.microsoft.com/playwright:v<version>-noble`). Screenshots taken on Windows or macOS render fonts differently and fail in CI.
-- Update baselines with `--update-snapshots=changed`, scoped to the spec you changed. `--update-snapshots=all` also rewrites accessible snapshots (`.aria.yml`) that didn't need to change.
-- Keep temporary files (scripts, specs, configs) outside the repo, e.g. in the system's temp folder. Vitest collects test files from every folder except the excluded ones in `vite.config.ts`, so a temporary spec in a gitignored folder such as `reports/` still runs, and fails, with the unit tests.
-- Never run Stryker at the same time as another test command: they share build output and Stryker fails with `ENOENT`.
-- Unit tests that mount several apps at once (e.g. nested dialogs) need a distinct `global.config.idPrefix` per mount, since `useId()` restarts in each app.
-- In E2E, a paused `page.clock` also freezes transitions, so overlays never finish leaving. Use `pauseClock(page)` from `e2e/utils.ts` to hold time-based work (e.g. a demo action with `setTimeout`), `page.clock.fastForward` to complete it, then `page.clock.resume()` before expecting the overlay to be hidden (see `e2e/composables/use-confirm.spec.ts`). Don't call `page.clock.pauseAt` with the test runner's time (`new Date()`, `Date.now()`): the page clock can be ahead of it, and the pause then fails with "Cannot fast-forward to the past". `pauseClock` pauses from the page's own time instead.
-
-## Public API design
-
-The public API is hard to change once released, and every prop, event or option is something consumers can misuse and maintainers must keep. Keep it minimal:
-
-- Only add what the issue asks for. Anything beyond it (an extra prop, event, option or variant) is a separate decision the maintainers must approve explicitly, not a default.
-- Behaviors meant to be consistent across the library aren't per-instance options. For example, every dialog closes with `Esc`, a click outside it or the browser's back button; a flag to block that stays internal.
-- Reuse existing contracts before creating new ones: `v-model` for open/closed state instead of extra lifecycle events such as `afterLeave`, the `actions` shape of `USection` for buttons, the option names of existing composables.
-
-## Library documentation and dependencies
-
-The stack is newer than most AI models' training data (Vue 3.5, Vuetify 4, Vue Router 5, Vite+ 0.2, Vitest 4, TypeScript 6, VitePress 2 alpha, Stryker 10, Playwright 1.62), so don't rely on memory for library APIs.
-
-- Before using an API this repo doesn't use yet, or implementing something from scratch, look it up in the version declared in `package.json`. The project's `.mcp.json` provides two servers for that:
-  - `context7`, with these library IDs: Vue `/websites/vuejs`, Vuetify `/websites/vuetifyjs_en`, Vue Router `/websites/router_vuejs`, Vite+ `/websites/viteplus_dev`, Vitest `/vitest-dev/vitest`, Vue Test Utils `/vuejs/test-utils`, Playwright `/microsoft/playwright`, VitePress `/vuejs/vitepress`, Stryker `/stryker-mutator/stryker-js`.
-  - `vuetify`, Vuetify's own server, for component and composable APIs and release notes. Its tools that create or update bins, links, playgrounds or bug reports publish content outside the repo and are denied in `.claude/settings.json`.
-  - Queries to both servers leave your machine: describe what you need in generic terms and never include source code or business rules.
-- Before adding a dependency, check whether Vuetify, `@nexdom/shared` or the current dependencies already cover the need. If not, confirm with the requester, check the package's docs, maintenance and license, and declare runtime dependencies as `peerDependencies` (enforced by dependency-cruiser's `use-peer-deps` rule).
-- Vuetify is an internal detail: consumers use the library's props, and `docs` never mention Vuetify.
-
-## AI agents
-
-Besides this file, the repo ships Claude Code subagents in `.claude/agents/`:
-
-- `issue-planner`: turns an issue into an API proposal plus open questions, before any code is written.
-- `issue-implementer`: implements an issue end to end (source, tests, docs, E2E).
-- `code-reviewer`: reviews a branch or PR against these conventions, without changing code.
-- `dependency-updater`: evaluates and applies dependency updates, such as Dependabot PRs.
-
-Issues and PRs live in `nexdom-healthtech/uimed-vue`. Pass `-R nexdom-healthtech/uimed-vue` to `gh`, since clones from forks have issues disabled, and read issues with `gh issue view <number> -R nexdom-healthtech/uimed-vue --json title,body,comments` (`--comments` prints nothing in non-interactive shells).
-
-To resolve an issue, run `/resolve-issue <number>` (`.claude/skills/resolve-issue/`). It chains planner, implementer and reviewer, asks you about open questions and waits for your approval of the public API before any code is written.
-
-## 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