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

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

@@ -0,0 +1,323 @@
+# Componentes para layout
+
+O layout do UIMed-Vue é baseado no [Grid system do Bootstrap](https://getbootstrap.com/docs/4.0/layout/grid/), dividindo cada linha em 12 colunas.
+
+Os componentes que implementam esse _grid system_ são:
+
+| Componente  | Descrição                                                                             |
+| ----------- | ------------------------------------------------------------------------------------- |
+| `Container` | componente central que agrupa diversas linhas.                                        |
+| `Row`       | componente secundário, para linhas, que agrupa diversas colunas.                      |
+| `Column`    | componente secundário, para colunas, que gerencia o conteúdo final a ser apresentado. |
+
+## Container, Linhas e colunas
+
+O `Container` encapsula diversas linhas, chamadas de `Row`, e esta agrupa diversas colunas, chamadas de `Column`.
+
+Cada coluna é capaz de ajustar o seu próprio tamanho para ocupar um determinado número de colunas, dentre as 12 disponíveis na linha inteira.
+
+### Uso
+
+```vue
+<template>
+  <u-main>
+    <u-container>
+      <u-row>
+        <u-column cols="auto">
+          <div style="background: lightgreen;">
+            <p>Linha 1 / Coluna 1</p>
+            <p>
+              <small>Tamanho <code>"auto"</code></small>
+            </p>
+          </div>
+        </u-column>
+        <u-column>
+          <div style="background: lightgreen;">
+            <p>Linha 2 / Coluna 1</p>
+            <p>
+              <small>Tamanho <code>"default"</code> (<code>"12"</code>)</small>
+            </p>
+          </div>
+        </u-column>
+      </u-row>
+      <u-row>
+        <u-column cols="6">
+          <div style="background: lightgreen;">
+            <p>Linha 3 / Coluna 1</p>
+            <p>
+              <small>Tamanho <code>"6"</code></small>
+            </p>
+          </div>
+        </u-column>
+        <u-column cols="6">
+          <div style="background: lightgreen;">
+            <p>Linha 3 / Coluna 2</p>
+            <p>
+              <small>Tamanho <code>"6"</code></small>
+            </p>
+          </div>
+        </u-column>
+      </u-row>
+      <u-row>
+        <u-column cols="4">
+          <div style="background: lightgreen;">
+            <p>Linha 4 / Coluna 1</p>
+            <p>
+              <small>Tamanho <code>"4"</code></small>
+            </p>
+          </div>
+        </u-column>
+        <u-column cols="4">
+          <div style="background: lightgreen;">
+            <p>Linha 4 / Coluna 2</p>
+            <p>
+              <small>Tamanho <code>"4"</code></small>
+            </p>
+          </div>
+        </u-column>
+        <u-column cols="4">
+          <div style="background: lightgreen;">
+            <p>Linha 4 / Coluna 3</p>
+            <p>
+              <small>Tamanho <code>"4"</code></small>
+            </p>
+          </div>
+        </u-column>
+      </u-row>
+    </u-container>
+  </u-main>
+</template>
+
+<script lang="ts" setup>
+import { UContainer, UMain, URow, UColumn } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+## Linhas e colunas como lista
+
+Quando as colunas de uma linha apresentam itens de uma mesma lista, como os cartões de uma listagem de pacientes, utilize a prop `list` na `Row` e a prop `listItem` em cada uma das suas `Column`s.
+
+Assim, a linha passa a ser uma lista e as colunas, os seus itens, e as tecnologias assistivas, como leitores de tela, anunciam a quantidade de itens e a posição de cada um deles. A aparência da grade não muda: a lista não recebe recuo nem marcadores.
+
+```vue
+<template>
+  <u-main>
+    <u-container>
+      <u-row list>
+        <u-column v-for="especialidade in especialidades" :key="especialidade" cols="4" list-item>
+          <div style="background: lightgreen;">
+            <p>{{ especialidade }}</p>
+          </div>
+        </u-column>
+      </u-row>
+    </u-container>
+  </u-main>
+</template>
+
+<script lang="ts" setup>
+import { UContainer, UMain, URow, UColumn } from "@nexdom/uimed-vue/components";
+
+const especialidades = ["Cardiologia", "Dermatologia", "Pediatria"];
+</script>
+```
+
+## Alinhamento vertical das colunas
+
+A prop `alignY` (`align-y` no template) da `Row` define como as suas colunas se alinham verticalmente em relação à coluna mais alta da mesma linha:
+
+| Valor       | Alinhamento                                               |
+| ----------- | --------------------------------------------------------- |
+| `"start"`   | no topo (padrão).                                         |
+| `"center"`  | ao centro.                                                |
+| `"end"`     | na base.                                                  |
+| `"stretch"` | estica todas as colunas até a altura da coluna mais alta. |
+
+Com `stretch`, é a coluna que cresce até a altura da mais alta: o seu conteúdo só a preenche visualmente quando também ocupa a altura toda, como as caixas do exemplo abaixo ou um [`USection`](./section.md) com `fullHeight`. Por isso, utilize `stretch` para manter colunas lado a lado com a mesma altura, como cartões.
+
+As colunas só ficam lado a lado em telas a partir de 600px de largura. Em telas menores, cada coluna ocupa uma linha inteira e o alinhamento não tem efeito visível, exceto em [linhas com altura total](#altura-total), em que as colunas são alinhadas, em conjunto, dentro da altura da linha.
+
+```vue
+<template>
+  <u-main>
+    <u-container>
+      <u-row align-y="start">
+        <u-column cols="4">
+          <div style="background: lightgreen; height: 100%;">
+            <code>align-y="start"</code>
+          </div>
+        </u-column>
+        <u-column cols="4">
+          <div style="background: lightgreen; height: 100%;">
+            Coluna mais alta<br />com<br />quatro<br />linhas
+          </div>
+        </u-column>
+        <u-column cols="4">
+          <div style="background: lightgreen; height: 100%;">Coluna com<br />duas linhas</div>
+        </u-column>
+      </u-row>
+      <u-row align-y="center">
+        <u-column cols="4">
+          <div style="background: lightgreen; height: 100%;">
+            <code>align-y="center"</code>
+          </div>
+        </u-column>
+        <u-column cols="4">
+          <div style="background: lightgreen; height: 100%;">
+            Coluna mais alta<br />com<br />quatro<br />linhas
+          </div>
+        </u-column>
+        <u-column cols="4">
+          <div style="background: lightgreen; height: 100%;">Coluna com<br />duas linhas</div>
+        </u-column>
+      </u-row>
+      <u-row align-y="end">
+        <u-column cols="4">
+          <div style="background: lightgreen; height: 100%;">
+            <code>align-y="end"</code>
+          </div>
+        </u-column>
+        <u-column cols="4">
+          <div style="background: lightgreen; height: 100%;">
+            Coluna mais alta<br />com<br />quatro<br />linhas
+          </div>
+        </u-column>
+        <u-column cols="4">
+          <div style="background: lightgreen; height: 100%;">Coluna com<br />duas linhas</div>
+        </u-column>
+      </u-row>
+      <u-row align-y="stretch">
+        <u-column cols="4">
+          <div style="background: lightgreen; height: 100%;">
+            <code>align-y="stretch"</code>
+          </div>
+        </u-column>
+        <u-column cols="4">
+          <div style="background: lightgreen; height: 100%;">
+            Coluna mais alta<br />com<br />quatro<br />linhas
+          </div>
+        </u-column>
+        <u-column cols="4">
+          <div style="background: lightgreen; height: 100%;">Coluna com<br />duas linhas</div>
+        </u-column>
+      </u-row>
+    </u-container>
+  </u-main>
+</template>
+
+<script lang="ts" setup>
+import { UContainer, UMain, URow, UColumn } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+## Alinhamento horizontal das colunas
+
+A prop `alignX` (`align-x` no template) da `Row` define como as suas colunas se alinham horizontalmente em cada linha:
+
+| Valor      | Alinhamento                  |
+| ---------- | ---------------------------- |
+| `"start"`  | no início da linha (padrão). |
+| `"center"` | ao centro.                   |
+| `"end"`    | no fim da linha.             |
+
+O alinhamento só tem efeito visível quando as colunas não preenchem a linha toda, como com `cols="auto"`, em que a coluna ocupa apenas a largura do seu conteúdo, ou com tamanhos que somam menos de 12. Quando as colunas não cabem em uma linha e passam para a seguinte, cada linha é alinhada separadamente.
+
+As colunas só ficam lado a lado em telas a partir de 600px de largura. Em telas menores, cada coluna ocupa uma linha inteira, mesmo com `cols="auto"`, e o alinhamento não tem efeito visível.
+
+`start` e `end` acompanham a direção do texto: em idiomas escritos da direita para a esquerda, `start` fica à direita e `end`, à esquerda.
+
+```vue
+<template>
+  <u-main>
+    <u-container>
+      <u-row align-x="start">
+        <u-column cols="auto">
+          <div style="background: lightgreen;">
+            <code>align-x="start"</code>
+          </div>
+        </u-column>
+      </u-row>
+      <u-row align-x="center">
+        <u-column cols="auto">
+          <div style="background: lightgreen;">
+            <code>align-x="center"</code>
+          </div>
+        </u-column>
+      </u-row>
+      <u-row align-x="end">
+        <u-column cols="auto">
+          <div style="background: lightgreen;">
+            <code>align-x="end"</code>
+          </div>
+        </u-column>
+      </u-row>
+    </u-container>
+  </u-main>
+</template>
+
+<script lang="ts" setup>
+import { UContainer, UMain, URow, UColumn } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+Com uma coluna `cols="auto"` e `align-x="center"`, por exemplo, o formulário de uma tela de login fica centralizado na linha, sem estilos próprios (para centralizá-lo também na altura da tela, veja [Altura total](#altura-total)):
+
+```vue
+<template>
+  <u-row align-x="center">
+    <u-column cols="auto">
+      <u-section title="Entrar">
+        <!-- formulário -->
+      </u-section>
+    </u-column>
+  </u-row>
+</template>
+
+<script lang="ts" setup>
+import { URow, UColumn, USection } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+## Altura total
+
+Por padrão, uma `Row` cresce apenas até a altura do seu conteúdo. Com a prop `fullHeight` (`full-height` no template), ela ocupa toda a altura visível da área de conteúdo do [`UMain`](./main.md), descontado o menu superior, quando houver.
+
+Combinada às props `alignY` e `alignX`, a linha posiciona as suas colunas nessa altura. Com `align-y="center"` e `align-x="center"`, por exemplo, o formulário de uma tela de login fica centralizado na tela, nos dois eixos:
+
+```vue
+<template>
+  <u-main :app-bar="{ title: 'Acesso' }">
+    <u-row full-height align-y="center" align-x="center">
+      <u-column cols="auto">
+        <u-section title="Entrar" subtitle="Informe os seus dados de acesso" :actions>
+          <u-section-content>
+            <!-- formulário -->
+          </u-section-content>
+        </u-section>
+      </u-column>
+    </u-row>
+  </u-main>
+</template>
+
+<script lang="ts" setup>
+import type { ComponentProps } from "vue-component-type-helpers";
+import { UMain, URow, UColumn, USection, USectionContent } from "@nexdom/uimed-vue/components";
+
+type SectionAction = NonNullable<ComponentProps<typeof USection>["actions"]>[number];
+
+const actions: SectionAction[] = [{ label: "Entrar", onClick: () => window.alert("Entrando...") }];
+</script>
+```
+
+Em telas com menos de 600px de largura, em que cada coluna ocupa uma linha inteira, as colunas continuam alinhadas, em conjunto, conforme a prop `alignY`.
+
+A linha com `fullHeight` ocupa sozinha toda a altura disponível: outras linhas ao seu lado ficam abaixo da área visível. Por isso, utilize-a como a única linha da página.
+
+Para que um [`UContainer`](../../api/components/grid/container.md) dentro do `UMain` também ocupe toda a altura disponível, e as suas linhas com `fullHeight` possam ocupá-la, utilize a prop `fullHeight` também no `UContainer`.
+
+## Playground
+
+Experimente os valores das props `alignY` e `alignX`.
+
+## Ver também
+
+Consulte a referência de [API do UContainer](../../api/components/grid/container.md), [da URow](../../api/components/grid/row.md) e [da UColumn](../../api/components/grid/column.md) para a lista completa de props, slots e eventos.

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

@@ -0,0 +1,47 @@
+# Links
+
+O componente padrão para exibir links de texto se chama `Link`.
+
+> [!Warning]
+> Deve ser utilizado no lugar do `<a>` nativo e do `<router-link>`.
+
+O texto do link é informado pelo slot padrão e também é o nome lido pelos leitores de tela. Por isso, ele deve descrever o destino do link (por exemplo, "Esqueceu sua senha?" em vez de "Clique aqui").
+
+Use o link para links avulsos, como um "Esqueceu sua senha?" abaixo de um formulário de login. Ele não é sublinhado, então não o use no meio de um parágrafo de texto, onde só a cor o distinguiria do texto ao redor. Para executar ações, use o [Button](./button.md).
+
+## Propriedades
+
+### Rota da aplicação
+
+A prop `route` define o destino do link. Uma rota da aplicação, como `"/login"` ou `{ name: "forgot-password" }`, navega sem recarregar a página. Enquanto essa rota é a página atual, o link é anunciado como a página atual pelos leitores de tela.
+
+> [!Warning]
+> Rotas da aplicação só funcionam em aplicações que usam o [Vue Router](https://router.vuejs.org/).
+
+```vue
+<template>
+  <u-link :route="{ name: 'forgot-password' }">Esqueceu sua senha?</u-link>
+</template>
+
+<script lang="ts" setup>
+import { ULink } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+### Endereço externo
+
+Um endereço que começa com `http` navega pelo navegador, na mesma aba, sem passar pelas rotas da aplicação.
+
+```vue
+<template>
+  <u-link route="https://nexdom-healthtech.github.io/shared/">Documentação do Shared</u-link>
+</template>
+
+<script lang="ts" setup>
+import { ULink } from "@nexdom/uimed-vue/components";
+</script>
+```
+
+## Ver também
+
+Consulte a referência de [API do ULink](../../api/components/link.md) para a lista completa de props.