matcha-components 20.13.0 → 20.15.0

package/src/documentation/services/matcha-breakpoint-observer.mdx

@@ -0,0 +1,310 @@
+import { Meta, Story, Canvas, Controls } from '@storybook/addon-docs';
+import { MatchaBreakpointObserver } from '../../lib/matcha-breakpoint-observable/breakpoint-observer.service';
+
+<Meta title="Services/MatchaBreakpointObserver" component={MatchaBreakpointObserver} />
+
+# MatchaBreakpointObserver
+
+O **MatchaBreakpointObserver** é um serviço singleton para observação de breakpoints CSS em aplicações Angular. Ele oferece uma API familiar e performática para detectar mudanças de tamanho de tela sem dependências externas.
+
+## Características
+
+- ✅ **Singleton**: Uma única instância em toda a aplicação
+- ✅ **SSR Compatible**: Funciona no servidor e no cliente
+- ✅ **Cache Inteligente**: Evita recálculos desnecessários
+- ✅ **Performance Otimizada**: Debounce automático para eventos resize
+- ✅ **API Familiar**: Interface similar ao Angular CDK
+- ✅ **Zero Dependências**: Angular puro, sem bibliotecas externas
+- ✅ **Múltiplos Breakpoints**: Observe vários breakpoints simultaneamente
+
+## Uso Básico
+
+```typescript
+import { MatchaBreakpointObserver } from '@matcha-components';
+
+export class MyComponent {
+  constructor(private breakpointObserver: MatchaBreakpointObserver) {}
+
+  ngOnInit() {
+    // Observa um breakpoint específico
+    this.breakpointObserver.observe('(max-width: 768px)')
+      .subscribe(result => {
+        console.log('Mobile:', result.matches);
+      });
+  }
+}
+```
+
+## API Reference
+
+### Métodos
+
+#### `observe(breakpoint: string): Observable<BreakpointState>`
+Observa um breakpoint específico e retorna um Observable que emite quando o estado muda.
+
+```typescript
+this.breakpointObserver.observe('(max-width: 768px)')
+  .subscribe(result => {
+    if (result.matches) {
+      console.log('Tela é mobile');
+    }
+  });
+```
+
+#### `isMatched(breakpoint: string): boolean`
+Verifica se um breakpoint específico está ativo no momento atual.
+
+```typescript
+const isMobile = this.breakpointObserver.isMatched('(max-width: 768px)');
+```
+
+#### `getState(breakpoint: string): BreakpointState`
+Obtém o estado atual de um breakpoint específico.
+
+```typescript
+const state = this.breakpointObserver.getState('(max-width: 768px)');
+console.log(state.matches); // true/false
+console.log(state.breakpoint); // "(max-width: 768px)"
+```
+
+#### `observeMultiple(breakpoints: string[]): Observable<Map<string, boolean>>`
+Observa múltiplos breakpoints simultaneamente.
+
+```typescript
+this.breakpointObserver.observeMultiple([
+  '(max-width: 768px)',
+  '(min-width: 1024px)'
+]).subscribe(breakpoints => {
+  const isMobile = breakpoints.get('(max-width: 768px)');
+  const isDesktop = breakpoints.get('(min-width: 1024px)');
+});
+```
+
+### Breakpoints Pré-definidos
+
+```typescript
+MatchaBreakpointObserver.BREAKPOINTS = {
+  XS: '(max-width: 480px)',           // Extra Small
+  SM: '(max-width: 768px)',           // Small
+  MD: '(max-width: 1024px)',          // Medium
+  LG: '(max-width: 1200px)',          // Large
+  XL: '(max-width: 1440px)',          // Extra Large
+  MOBILE: '(max-width: 768px)',       // Mobile
+  TABLET: '(min-width: 769px) and (max-width: 1024px)', // Tablet
+  DESKTOP: '(min-width: 1025px)'      // Desktop
+}
+```
+
+### Método Utilitário
+
+#### `createBreakpoint(width: number, condition: 'max' | 'min'): string`
+Cria um breakpoint de forma programática.
+
+```typescript
+const mobileBreakpoint = MatchaBreakpointObserver.createBreakpoint(768, 'max');
+// Retorna: "(max-width: 768px)"
+
+const desktopBreakpoint = MatchaBreakpointObserver.createBreakpoint(1024, 'min');
+// Retorna: "(min-width: 1024px)"
+```
+
+## Exemplos Práticos
+
+### 1. Componente Responsivo
+
+```typescript
+import { Component, OnInit, OnDestroy } from '@angular/core';
+import { MatchaBreakpointObserver, BreakpointState } from '@matcha-components';
+import { Subscription } from 'rxjs';
+
+@Component({
+  selector: 'app-responsive-component',
+  template: `
+    <div [class.mobile]="isMobile" [class.desktop]="!isMobile">
+      <h1>{{ isMobile ? 'Mobile View' : 'Desktop View' }}</h1>
+    </div>
+  `
+})
+export class ResponsiveComponent implements OnInit, OnDestroy {
+  isMobile = false;
+  private subscription?: Subscription;
+
+  constructor(private breakpointObserver: MatchaBreakpointObserver) {}
+
+  ngOnInit() {
+    this.subscription = this.breakpointObserver
+      .observe(MatchaBreakpointObserver.BREAKPOINTS.MOBILE)
+      .subscribe((state: BreakpointState) => {
+        this.isMobile = state.matches;
+      });
+  }
+
+  ngOnDestroy() {
+    if (this.subscription) {
+      this.subscription.unsubscribe();
+    }
+  }
+}
+```
+
+### 2. Múltiplos Breakpoints
+
+```typescript
+@Component({
+  selector: 'app-multi-breakpoint',
+  template: `
+    <div [ngSwitch]="currentView">
+      <div *ngSwitchCase="'mobile'">Mobile Content</div>
+      <div *ngSwitchCase="'tablet'">Tablet Content</div>
+      <div *ngSwitchCase="'desktop'">Desktop Content</div>
+    </div>
+  `
+})
+export class MultiBreakpointComponent implements OnInit {
+  currentView = 'desktop';
+
+  constructor(private breakpointObserver: MatchaBreakpointObserver) {}
+
+  ngOnInit() {
+    this.breakpointObserver.observeMultiple([
+      MatchaBreakpointObserver.BREAKPOINTS.MOBILE,
+      MatchaBreakpointObserver.BREAKPOINTS.TABLET,
+      MatchaBreakpointObserver.BREAKPOINTS.DESKTOP
+    ]).subscribe(breakpoints => {
+      if (breakpoints.get(MatchaBreakpointObserver.BREAKPOINTS.MOBILE)) {
+        this.currentView = 'mobile';
+      } else if (breakpoints.get(MatchaBreakpointObserver.BREAKPOINTS.TABLET)) {
+        this.currentView = 'tablet';
+      } else {
+        this.currentView = 'desktop';
+      }
+    });
+  }
+}
+```
+
+### 3. Layout Dinâmico
+
+```typescript
+@Component({
+  selector: 'app-dynamic-layout',
+  template: `
+    <div class="layout" [class.sidebar-collapsed]="sidebarCollapsed">
+      <aside class="sidebar" *ngIf="showSidebar">
+        <nav>Sidebar Content</nav>
+      </aside>
+      <main class="content">
+        <button (click)="toggleSidebar()">Toggle Sidebar</button>
+        <p>Main Content</p>
+      </main>
+    </div>
+  `
+})
+export class DynamicLayoutComponent implements OnInit {
+  showSidebar = true;
+  sidebarCollapsed = false;
+
+  constructor(private breakpointObserver: MatchaBreakpointObserver) {}
+
+  ngOnInit() {
+    // Auto-colapsa sidebar em mobile
+    this.breakpointObserver.observe('(max-width: 768px)')
+      .subscribe(result => {
+        this.sidebarCollapsed = result.matches;
+        this.showSidebar = !result.matches;
+      });
+  }
+
+  toggleSidebar() {
+    this.sidebarCollapsed = !this.sidebarCollapsed;
+  }
+}
+```
+
+## Integração com Outros Componentes
+
+### MatchaDrawer
+
+O MatchaDrawer usa internamente o MatchaBreakpointObserver para responsividade:
+
+```typescript
+// O drawer automaticamente usa o breakpoint observer
+<matcha-drawer
+  [responsiveMode]="true"
+  [mobileBreakpoint]="768"
+  [mobileMode]="'overlay'"
+  [desktopMode]="'push'">
+  <!-- Conteúdo do drawer -->
+</matcha-drawer>
+```
+
+### Componentes Customizados
+
+```typescript
+@Component({
+  selector: 'app-custom-responsive',
+  template: `
+    <div class="grid" [class.grid-mobile]="isMobile">
+      <div class="grid-item" *ngFor="let item of items">
+        {{ item }}
+      </div>
+    </div>
+  `
+})
+export class CustomResponsiveComponent implements OnInit {
+  items = ['Item 1', 'Item 2', 'Item 3'];
+  isMobile = false;
+
+  constructor(private breakpointObserver: MatchaBreakpointObserver) {}
+
+  ngOnInit() {
+    this.breakpointObserver.observe('(max-width: 768px)')
+      .subscribe(result => {
+        this.isMobile = result.matches;
+      });
+  }
+}
+```
+
+## Performance e Otimizações
+
+### Cache Inteligente
+O serviço mantém um cache interno dos breakpoints verificados, evitando recálculos desnecessários.
+
+### Debounce Automático
+Os eventos de resize são debounced com 100ms para evitar muitas chamadas durante o redimensionamento.
+
+### Singleton Pattern
+Uma única instância do serviço é compartilhada em toda a aplicação, garantindo eficiência de memória.
+
+### SSR Compatible
+O serviço funciona tanto no servidor quanto no cliente, retornando valores seguros durante a renderização no servidor.
+
+## Troubleshooting
+
+### Breakpoint não detecta mudanças
+- Verifique se o breakpoint está no formato correto: `(max-width: 768px)`
+- O observer usa debounce de 100ms, aguarde um momento após redimensionar
+- Certifique-se de que está no browser (não funciona no servidor)
+
+### Performance lenta
+- Use `observeMultiple()` para observar vários breakpoints de uma vez
+- Evite criar muitas subscrições desnecessárias
+- O cache interno otimiza automaticamente as verificações
+
+### Problemas de SSR
+- O serviço retorna `false` no servidor por segurança
+- Use `isPlatformBrowser()` se precisar de comportamento específico no cliente
+
+### Memory Leaks
+- Sempre unsubscribe das observações no `ngOnDestroy`
+- O serviço é singleton, mas as subscrições precisam ser gerenciadas
+
+## Casos de Uso Comuns
+
+1. **Layouts Responsivos**: Adaptar layouts baseado no tamanho da tela
+2. **Navegação Mobile**: Mostrar/esconder elementos em mobile
+3. **Grids Dinâmicos**: Ajustar número de colunas baseado no breakpoint
+4. **Modais e Drawers**: Comportamento diferente em mobile/desktop
+5. **Imagens Responsivas**: Carregar diferentes tamanhos de imagem
+6. **Formulários**: Layouts diferentes para mobile/desktop

package/src/documentation/tokens/animations.mdx

@@ -0,0 +1,116 @@
+import { Meta } from "@storybook/addon-docs";
+
+<Meta title="Tokens / Animations" />
+
+# Animations
+
+Os tokens de animações definem as curvas de easing e as durações padrão usadas no design do material.
+
+### Atributos
+<div class="w-100-p">
+    <table class="w-100-p">
+        <thead>
+            <tr>
+                <th>Token</th>
+                <th>Propriedade</th>
+            </tr>
+        </thead>
+        <tbody>
+            <tr>
+                <td>$time-transition-minimal</td>
+                <td>80ms</td>
+            </tr>
+            <tr>
+                <td>$time-transition-short</td>
+                <td>200ms</td>
+            </tr>
+            <tr>
+                <td>$time-transition-base</td>
+                <td>400ms</td>
+            </tr>
+            <tr>
+                <td>$time-transition-long</td>
+                <td>600ms</td>
+            </tr>
+            <tr>
+                <td>$time-transition-xl</td>
+                <td>1000ms</td>
+            </tr>
+            <tr>
+                <td>$time-delay-short</td>
+                <td>50ms</td>
+            </tr>
+            <tr>
+                <td>$time-delay-base</td>
+                <td>100ms</td>
+            </tr>
+            <tr>
+                <td>$time-delay-long</td>
+                <td>200ms</td>
+            </tr>
+            <tr>
+                <td>$time-duration-short</td>
+                <td>2000ms</td>
+            </tr>
+            <tr>
+                <td>$time-duration-base</td>
+                <td>4000ms</td>
+            </tr>
+            <tr>
+                <td>$time-duration-long</td>
+                <td>6000ms</td>
+            </tr>
+            <tr>
+                <td>$matcha-linear-out-slow-in-timing-function</td>
+                <td>cubic-bezier(0, 0, 0.2, 0.1)</td>
+            </tr>
+            <tr>
+                <td>$matcha-fast-out-slow-in-timing-function</td>
+                <td>cubic-bezier(0.4, 0, 0.2, 1)</td>
+            </tr>
+            <tr>
+                <td>$matcha-fast-out-linear-in-timing-function</td>
+                <td>cubic-bezier(0.4, 0, 1, 1)</td>
+            </tr>
+            <tr>
+                <td>$ease-in-out-curve-function</td>
+                <td>cubic-bezier(0.35, 0, 0.25, 1)</td>
+            </tr>
+            <tr>
+                <td>$swift-ease-out-duration</td>
+                <td>400ms</td>
+            </tr>
+            <tr>
+                <td>$swift-ease-out-timing-function</td>
+                <td>cubic-bezier(0.25, 0.8, 0.25, 1)</td>
+            </tr>
+            <tr>
+                <td>$swift-ease-in-duration</td>
+                <td>200ms</td>
+            </tr>
+            <tr>
+                <td>$swift-ease-in-timing-function</td>
+                <td>cubic-bezier(0.55, 0, 0.55, 0.2)</td>
+            </tr>
+            <tr>
+                <td>$swift-ease-in-out-duration</td>
+                <td>600ms</td>
+            </tr>
+            <tr>
+                <td>$swift-ease-in-out-timing-function</td>
+                <td>cubic-bezier(0.35, 0, 0.25, 1)</td>
+            </tr>
+            <tr>
+                <td>$swift-linear-duration</td>
+                <td>80ms</td>
+            </tr>
+            <tr>
+                <td>$swift-linear-timing-function</td>
+                <td>linear</td>
+            </tr>
+        </tbody>
+    </table>
+</div>
+
+### Instalação
+Não é necessario instalar nenhuma dependência para utilizar os tokens. Os tokens são utilizados internamente em todas as bibliotecas do Matcha Design System. Portanto quando você importar qualquer biblioteca do Matcha Design System, você já estará utilizando os tokens dessa documentação.

package/src/documentation/tokens/breakpoints.mdx

@@ -0,0 +1,57 @@
+import { Meta } from "@storybook/addon-docs";
+
+<Meta title="Tokens / Breakpoints" />
+
+# Breakpoints
+
+Os tokens de breakpoints definem os pontos de interrupção de mídia usados para criar layouts responsivos.
+
+### Atributos
+<div class="w-100-p">
+    <table class="w-100-p">
+        <thead>
+            <tr>
+                <th>Token</th>
+                <th>Propriedade</th>
+            </tr>
+        </thead>
+        <tbody>
+            <tr>
+                <td>$breakpoints</td>
+                <td>
+                    <pre>
+xs: 'screen and (max-width: 599px)',
+sm: 'screen and (min-width: 600px) and (max-width: 1023px)',
+md: 'screen and (min-width: 1024px) and (max-width: 1439px)',
+lg: 'screen and (min-width: 1440px) and (max-width: 1919px)',
+xl: 'screen and (min-width: 1920px) and (max-width: 5000px)',
+lt-sm: 'screen and (max-width: 599px)',
+lt-md: 'screen and (max-width: 1023px)',
+lt-lg: 'screen and (max-width: 1439px)',
+lt-xl: 'screen and (max-width: 1919px)',
+gt-xs: 'screen and (min-width: 600px)',
+gt-sm: 'screen and (min-width: 1024px)',
+gt-md: 'screen and (min-width: 1440px)',
+gt-lg: 'screen and (min-width: 1920px)'
+                    </pre>
+                </td>
+            </tr>
+            <tr>
+                <td>$helper-breakpoints</td>
+                <td>
+                    <pre>
+initial: null,
+xs: 'xs',
+sm: 'gt-xs',
+md: 'gt-sm',
+lg: 'gt-md',
+xl: 'gt-lg'
+                    </pre>
+                </td>
+            </tr>
+        </tbody>
+    </table>
+</div>
+
+### Instalação
+Não é necessário instalar nenhuma dependência para utilizar os tokens. Os tokens são utilizados internamente em todas as bibliotecas do Matcha Design System. Portanto, quando você importar qualquer biblioteca do Matcha Design System, você já estará utilizando os tokens dessa documentação.