snapport 0.1.0 → 0.1.1

package/README.md

@@ -1,150 +1,126 @@
 # Snap-Port 🚀
-O **Snap-Port** é uma biblioteca **vanilla JavaScript**, sem dependências, pensada para desenvolvedores que desejam automatizar a exibição de projetos do GitHub em sites pessoais ou portfólios.
+O **Snap-Port** é uma biblioteca desenvolvida em **TypeScript**, sem dependências externas, projetada para automatizar a exibição de projetos do GitHub em sites pessoais ou portfólios.
 
-A proposta é simples: você marca seus repositórios com a tag ``port`` no GitHub, e o Snap-Port se encarrega de **buscar, cachear, filtrar e renderizar** esses projetos na sua interface — eliminando a necessidade de atualizações manuais no código do site.
-
-> **Use o GitHub como fonte única de verdade para o seu portfólio.**
+A proposta central é utilizar o GitHub como **fonte única de verdade:** ao marcar seus repositórios com a tag escolhida, a biblioteca se encarrega de buscar, tratar, aplicar cache e renderizar os dados, eliminando a manutenção manual no código do seu site.
 
 ---
 
-## 🛠 O que a biblioteca oferece?
-
-A biblioteca foi desenhada para ser modular, funcionando tanto como um **motor de dados (headless)** quanto como uma **solução visual pronta para uso.**
+## 🛠 Funcionalidades Técnicas
 
-### 1. Camada de Dados (Headless)
+### 1. Seleção de Projetos e Controle de Stacks
+O Snap-Port oferece controle total sobre o que é exibido e como as tecnologias são categorizadas:
 
-Se você já possui seu próprio layout ou utiliza frameworks como **React** ou **Vue**, pode consumir apenas a lógica de dados.
+- **Tag de Descoberta**: Por padrão, a biblioteca busca repositórios com a tag ``port``, mas você pode definir qualquer outra tag no momento da inicialização.
+- **Filtros por Stacks (Topics):** Para que os filtros automáticos e a barra de busca funcionem corretamente, você deve listar as tecnologias (ex: ``react``, ``nodejs``, ``css``) nos topics do seu repositório no GitHub.
+- **Por que não usar a "Language" automática?** A lib ignora o campo ``language`` do GitHub para permitir que você decida quais ferramentas quer destacar. Isso evita que um projeto de React seja classificado apenas como "HTML" ou "JavaScript" devido ao volume de arquivos gerados por ferramentas de build, garantindo que o filtro reflita a stack real do projeto.
 
-O método ``getPortProjects`` retorna um JSON tratado, abstraindo o ruído da API do GitHub e entregando apenas o essencial:
+### 2. Gestão Inteligente de Imagens
+Como a API do GitHub não retorna links diretos de imagens de preview, o Snap-Port utiliza uma lógica de **geração automática** integrada aos componentes de UI.
 
-- Nome
-- Descrição
-- Tópicos
-- Link do repositório
-- Link de deploy
-- Linguagem principal
+Para que cada projeto tenha sua própria imagem, siga estas regras:
 
-Exemplo básico de uso:
-  ```bash
-    import { getPortProjects } from 'snap-port';
+- **Arquivo de Preview:** Você deve criar um arquivo chamado ``preview.png`` na raiz do seu repositório.
+- **Importante:** O nome deve ser exatamente preview.png (letras minúsculas), pois o GitHub diferencia maiúsculas de minúsculas (*case-sensitive*).
 
-    const projects = await getPortProjects('seu-usuario', 'topic-tag');
-  ```
+Caso o arquivo não exista ou ocorra algum erro de carregamento (como *Rate Limits*), a lib executa uma **estratégia de fallback em cascata:**
 
----
+- **GitHub Open Graph:** Tenta carregar o card dinâmico gerado pelo próprio GitHub.
+- **Placeholder de Segurança:** Se o GitHub bloquear a requisição, gera um card neutro contendo o nome do projeto via placehold.co.
 
-### 2. Componentes de UI (Plug & Play)
+### 3. Componentes de UI Integrados
 
-Para quem busca agilidade, o Snap-Port oferece componentes de interface prontos, que podem ser usados sem frameworks:
+- **Search Bar:** Filtro textual em tempo real (nome, descrição e tópicos).
+- **Filter** Carousel: Carrossel dinâmico baseado nos tópicos definidos nos repositórios.
+- **Project Cards (Layout 16:9):** Cards responsivos com badges de tecnologia e botões de ação (Código e Deploy).
 
-- **Search Bar**  
-  Filtro textual instantâneo que atua sobre os dados em cache.
+---
 
-- **Filter Carousel**  
-  Carrossel horizontal de tecnologias que identifica automaticamente suas stacks a partir dos tópicos do GitHub.
+## 💡 Dicas para um melhor Resultado
 
-- **Project Cards**  
-  Cards minimalistas que incluem:
-  - Social Preview (imagem do repositório)
-  - Descrição com limite de linhas
-  - Botões de ação para código-fonte e deploy
+- **Proporção de Imagem:** Para que as imagens não fiquem com partes cortadas nos cards, salve seus arquivos ``preview.png`` na proporção **16:9** (ex: 1280x720px).
+- **Link de Acesso (Deploy):** O botão "Acessar" só aparecerá se o campo **"Homepage"** estiver preenchido nas configurações do seu repositório no GitHub.
 
 ---
 
-## 🚀 Instalação e Uso
+## 📦 Instalação e Integração
 
 ### Via NPM
 
 ```bash
-npm install snap-port
+npm install snapport
 ```
 
 ### Via CDN (Direto no HTML)
-Se preferir não usar gerenciadores de pacotes, você pode importar os arquivos de distribuição diretamente:
 
-```bash
-<!-- Estilos da Lib -->
-<link rel="stylesheet" href="https://unpkg.com/snap-port/dist/snap-port.css">
+```html
+<!-- 1. Estilos da Biblioteca -->
+<link rel="stylesheet" href="https://cdn.jsdelivr.net">
 
-<!-- Lógica da Lib -->
+<!-- 2. Lógica e Inicialização -->
 <script type="module">
-  import { initPortfolio } from 'https://unpkg.com/snap-port/dist/snap-port.js';
+  import { initPortfolio } from 'https://cdn.jsdelivr.net';
 
   initPortfolio('seu-usuario', {
-    search: 'id-do-input',
-    filters: 'id-container-dos-filtros',
-    projects: 'id-do-grid'
+    tag: 'port',                      // Opcional: padrão é 'port'
+    searchContainer: 'id-search',     // ID do container da busca
+    filtersContainer: 'id-filters',   // ID do container dos filtros
+    projectsContainer: 'id-projects'  // ID do container do grid
   });
 </script>
 ```
 
-## ⚙️ Customização e Comportamento
-
-### Gerenciamento de Tags e Imagens
-
-A biblioteca utiliza os **topics** do seu repositório para duas funções:
-
-- **Filtro de Descoberta**  
-  Apenas repositórios com a tag **`port`** são processados.
-
-- **Identidade Visual**  
-  Tags como `react`, `nodejs` ou `typescript` são mapeadas para seus respectivos ícones e cores oficiais.
-
-- **Imagens**  
-  O Snap-Port consome o **Open Graph** do repositório para exibir automaticamente a imagem de preview do projeto.
-
----
-
-### Cache, Performance e Rate Limit
-
-Para evitar chamadas excessivas à API do GitHub e reduzir impactos de **rate limit**, o Snap-Port implementa um **sistema de cache inteligente baseado em ``localStorage``**.
-
-Esse sistema:
-
-- Armazena os dados tratados por usuário de forma isolada, evitando conflitos quando múltiplos portfólios utilizam a biblioteca no mesmo ambiente (ex: recrutadores abrindo vários ports).
-
-- Possui ciclo de expiração automática, garantindo que os dados sejam atualizados periodicamente (entre 1 e 2 horas).
-
-- Realiza limpeza automática de entradas antigas, funcionando como um garbage collector manual, evitando crescimento indefinido do localStorage.
-
-- Trata casos de borda para impedir reutilização indevida de cache entre usuários diferentes.
-
-Na prática, isso garante:
-
-- Melhor performance,
-
-- Menos requisições,
-
-- E maior previsibilidade no consumo da API do GitHub.
-
 ---
 
-### Estilização
-
-A interface é construída com **variáveis CSS**, permitindo que você adapte as cores ao seu tema sem modificar o código interno:
+## 🎨 Personalização Visual (CSS Variables)
+Se você utiliza o layout padrão da biblioteca, pode adaptar as cores e o estilo ao seu tema sem modificar o código interno. O Snap-Port utiliza **Variáveis CSS** que podem ser facilmente sobrescritas no seu arquivo global:
 
 ```css
 :root {
-  --ghp-accent: #333;   /* Cor de destaque (botões ativos e ícones) */
-  --ghp-bg: #fff;       /* Fundo dos cards */
-  --ghp-border: #ddd;   /* Bordas e divisores */
+  --ghp-accent: #333;           /* Cor de destaque (botões e ícones) */
+  --ghp-bg: #ffffff;            /* Fundo dos cards */
+  --ghp-text: #333;             /* Título e textos principais */
+  --ghp-text-light: #666;       /* Descrições e textos secundários */
+  --ghp-border: rgba(226, 226, 228, 0.8); /* Bordas */
+  --ghp-shadow: rgba(0, 0, 0, 0.1);       /* Sombras dos cards */
 }
 ```
 
-## ⚠️ Status do Projeto e Contribuições
-
-Este projeto está em sua fase **MVP (Minimum Viable Product)**.  
+---
 
-Atualmente, os componentes de UI compartilham estado interno para otimizar filtragem e performance.
+## ⚙️ Customização e Performance
+
+### Injeção de Template Customizado
+Mantenha a inteligência de busca e cache, mas use seu próprio design:
+
+```javascript
+initPortfolio('seu-usuario', {
+  searchContainer: 'id-search',
+  filtersContainer: 'id-filters',
+  projectsContainer: 'id-projects',
+  customCardTemplate: (repo) => `
+    <div class="meu-card-personalizado">
+      <h4>${repo.name}</h4>
+      <p>${repo.description}</p>
+      <a href="${repo.htmlUrl}">Ver código</a>
+    </div>
+  `
+});
+```
 
-> Este projeto é mantido no tempo livre e não possui garantias de suporte contínuo. Mudanças na API do GitHub ou na própria biblioteca podem ocorrer sem aviso prévio.
+### Cache e Estabilidade
+A biblioteca utiliza localStorage para garantir performance:
 
-Sugestões, ideias de funcionalidades e relatos de bugs são bem-vindos.
-Sinta-se à vontade para abrir uma **Issue** ou enviar um **Pull Request**.
-Para detalhes sobre como contribuir, consulte o [**Guia de Contribuição.**](https://github.com/guilhermegodoydev/snap-port/blob/main/CONTRIBUTING.md)
+- **Persistência:** Dados armazenados por até 2 horas.
+- **Isolamento:** Cache separado por usuário do GitHub.
 
 ---
 
-**Autor:** Guilherme Godoy ([@guilhermegodoydev](https://github.com/guilhermegodoydev)) • **Licença:** MIT • **Peso:** 2.8kB gzipped
+⚠️ Status do Projeto
+Este projeto está em fase **v0.1.0 (MVP).** Ele foi desenvolvido para resolver uma necessidade real de automação de portfólios e continuará recebendo melhorias conforme o uso.
 
+> **Nota sobre Manutenção:**  
+> Este é um projeto de código aberto mantido de forma independente. Sinta-se à vontade para contribuir! Se encontrar um bug ou tiver uma ideia de funcionalidade, abrir uma **Issue** ou um **Pull Request** é a melhor forma de ajudar o projeto a crescer.
+>
+> Para entender como colaborar com o código, consulte o nosso [**Guia de Contribuição**](./CONTRIBUTING.md).
 
+**Autor**: Guilherme Godoy (@guilhermegodoydev) • **Licença**: MIT • **Peso**: ~3.12kB (Gzipped)

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export declare function getPortProjects(username: string, tag?: string): Promise
 export declare function initPortfolio(username: string, config?: PortfolioConfig): Promise<PortfolioResponse>;
 
 export declare interface PortfolioConfig {
+    tag?: string;
     searchContainer: string;
     filtersContainer: string;
     projectsContainer: string;

package/dist/snap-port.js

@@ -172,9 +172,10 @@ async function S(t, e = {
   projectsContainer: "projects-cont"
 }) {
   try {
+    const o = e.tag || "port";
     $(e.searchContainer), C(e.projectsContainer, 6);
-    const o = await y(t);
-    return w(o, e.filtersContainer), m(o, e.projectsContainer, t, e.customCardTemplate), b(e.filtersContainer, o, e.projectsContainer, t, e.customCardTemplate), E(o, e.projectsContainer, t, e.customCardTemplate), { projects: o, status: "success" };
+    const r = await y(t, o);
+    return w(r, e.filtersContainer), m(r, e.projectsContainer, t, e.customCardTemplate), b(e.filtersContainer, r, e.projectsContainer, t, e.customCardTemplate), E(r, e.projectsContainer, t, e.customCardTemplate), { projects: r, status: "success" };
   } catch (o) {
     console.error("Erro ao inicializar portfólio:", o);
     const r = document.getElementById(e.projectsContainer);

package/dist/snap-port.umd.cjs

@@ -40,4 +40,4 @@
       </svg>
       <input type="text" id="gh-port-search" class="ghp-search-input" placeholder="Buscar projeto..." autocomplete="off">
     </div>
-  `)}function E(e,t,o,r,n){const c=document.getElementById(e);c&&c.addEventListener("click",i=>{const l=i.target.closest(".ghp-filter-btn");if(!l)return;const p=l.dataset.topic,d=p==="all"?t:t.filter(g=>g.topics.includes(p));u(d,o,r,n),c.querySelectorAll(".ghp-filter-btn").forEach(g=>g.classList.remove("active")),l.classList.add("active")})}function B(e,t,o,r){const n=document.getElementById("gh-port-search");n&&n.addEventListener("input",c=>{const a=c.target.value.toLowerCase(),l=e.filter(p=>p.name.toLowerCase().includes(a)||(p.description||"").toLowerCase().includes(a)||p.topics.some(d=>d.toLowerCase().includes(a)));u(l,t,o,r)})}async function P(e,t={searchContainer:"search-cont",filtersContainer:"filters-cont",projectsContainer:"projects-cont"}){try{j(t.searchContainer),S(t.projectsContainer,6);const o=await f(e);return v(o,t.filtersContainer),u(o,t.projectsContainer,e,t.customCardTemplate),E(t.filtersContainer,o,t.projectsContainer,e,t.customCardTemplate),B(o,t.projectsContainer,e,t.customCardTemplate),{projects:o,status:"success"}}catch(o){console.error("Erro ao inicializar portfólio:",o);const r=document.getElementById(t.projectsContainer);return r&&(r.innerHTML='<p class="ghp-empty-msg">Erro ao carregar projetos.</p>'),{status:"error",message:o.message}}}s.getPortProjects=f,s.initPortfolio=P,s.renderFilters=v,s.renderProjects=u,s.renderSearchBar=j,Object.defineProperty(s,Symbol.toStringTag,{value:"Module"})}));
+  `)}function E(e,t,o,r,n){const c=document.getElementById(e);c&&c.addEventListener("click",i=>{const l=i.target.closest(".ghp-filter-btn");if(!l)return;const p=l.dataset.topic,d=p==="all"?t:t.filter(g=>g.topics.includes(p));u(d,o,r,n),c.querySelectorAll(".ghp-filter-btn").forEach(g=>g.classList.remove("active")),l.classList.add("active")})}function B(e,t,o,r){const n=document.getElementById("gh-port-search");n&&n.addEventListener("input",c=>{const a=c.target.value.toLowerCase(),l=e.filter(p=>p.name.toLowerCase().includes(a)||(p.description||"").toLowerCase().includes(a)||p.topics.some(d=>d.toLowerCase().includes(a)));u(l,t,o,r)})}async function P(e,t={searchContainer:"search-cont",filtersContainer:"filters-cont",projectsContainer:"projects-cont"}){try{const o=t.tag||"port";j(t.searchContainer),S(t.projectsContainer,6);const r=await f(e,o);return v(r,t.filtersContainer),u(r,t.projectsContainer,e,t.customCardTemplate),E(t.filtersContainer,r,t.projectsContainer,e,t.customCardTemplate),B(r,t.projectsContainer,e,t.customCardTemplate),{projects:r,status:"success"}}catch(o){console.error("Erro ao inicializar portfólio:",o);const r=document.getElementById(t.projectsContainer);return r&&(r.innerHTML='<p class="ghp-empty-msg">Erro ao carregar projetos.</p>'),{status:"error",message:o.message}}}s.getPortProjects=f,s.initPortfolio=P,s.renderFilters=v,s.renderProjects=u,s.renderSearchBar=j,Object.defineProperty(s,Symbol.toStringTag,{value:"Module"})}));

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "snapport",
   "private": false,
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "files": [
     "dist"