penta-pack

Modern frontend projeleri icin Vite + Tailwind CSS v4 odakli arac seti. Clamp generator, Tailwind variant'lari, Vite preset'leri ve JS utility'leri tek pakette sunar.

Ozellikler

• Clamp utility uretimi (class tabanli)
• Tailwind CSS v4 plugin (toggle, visible, starting)
• Vite preset'leri (server/build/optimizeDeps)
• Build version yardimcilari
• Handlebars helper seti
• JS UI util'leri (scroll, copy, toggle vb.)

Kurulum

Local path (gelistirme)

{
  "dependencies": {
    "penta-pack": "file:../penta-pack"
  }
}

NPM (yayinlandiginda)

npm install penta-pack
# veya
yarn add penta-pack

NPM Branch Workflow

main gelistirme branch'i olarak kalir. npm branch'i ise yalnizca publish edilecek dosyalari tutar.

npm run npm:sync

Bu komut:

• npm run build calistirir
• npm branch'ini gunceller
• dist/ icini duzlestirir ve branch kokune index.js, css/, js/, tailwind/, vite/ dosya ve klasorlerini koyar
• kokte ayrica package.json, README.md, readme-usage.md, LICENSE, VERSION, penta-pack.css dosyalari kalir

Yayin akisi:

git checkout npm
npm publish --otp=XXXXXX

Vite Entegrasyonu

import { defineConfig } from "vite";
import tailwindcss from "@tailwindcss/vite";
import handlebars from "vite-plugin-handlebars";
import { imageToWebpPlugin } from "vite-plugin-image-to-webp";
import {
  clampGeneratorPlugin,
  createAssetsFixPlugin,
  createBuildOutput,
  createHandlebarsHelpers,
  getBuildKey,
  getBuildVersion,
  loadJsonData,
  loadPages,
  createVitePresets,
} from "penta-pack";

export default defineConfig(({ command }) => {
  const pages = loadPages(__dirname);
  const globalData = loadJsonData(__dirname);
  const buildVersion = getBuildVersion(__dirname);
  const buildKey = getBuildKey(__dirname, command);

  return {
    root: "src",
    plugins: [
  clampGeneratorPlugin({
    srcDir: "./src",
    filePattern: [".hbs", ".html"],
    layer: true,
    cache: true,
    virtual: true
  }),
      handlebars({
        partialDirectory: "./src",
        context() {
          return globalData;
        },
        helpers: createHandlebarsHelpers(buildVersion),
      }),
      tailwindcss(),
      imageToWebpPlugin({
        imageFormats: ["jpg", "jpeg", "png"],
        quality: 80,
        attributes: ["src", "data-src"],
      }),
      createAssetsFixPlugin(),
    ],
    ...createVitePresets(__dirname),
    server: {
      ...createVitePresets(__dirname).server,
      open: "/index.html",
    },
    build: {
      ...createVitePresets(__dirname).build,
      rollupOptions: {
        input: {
          ...pages,
          main: "./src/script/script.js",
          style: "./src/style/style.css",
        },
        output: {
          ...createBuildOutput(buildKey),
        },
      },
    },
  };
});

Tailwind Entegrasyonu

@import "tailwindcss";
@plugin '@tailwindcss/typography';
@plugin 'penta-pack/tailwind/pentail-plugin.js';
@import "penta-pack/penta-pack.css";
/* Clamp class'ları artık otomatik olarak @plugin içinde üretilir, virtual import'a gerek yoktur. */

Swiper CSS (Parçalı)

Genel Swiper CSS:

@import "penta-pack/css/swiper";

İhtiyaca göre modüller:

@import "penta-pack/css/swiper-navigation";
@import "penta-pack/css/swiper-pagination";
@import "penta-pack/css/swiper-scrollbar";
@import "penta-pack/css/swiper-grid";
@import "penta-pack/css/swiper-effect-fade";
@import "penta-pack/css/swiper-effect-cube";
@import "penta-pack/css/swiper-effect-flip";
@import "penta-pack/css/swiper-effect-creative";
@import "penta-pack/css/swiper-effect-cards";
@import "penta-pack/css/swiper-effect-coverflow";
@import "penta-pack/css/swiper-zoom";

Clamp Kullanimi

<h1 class="clamp-text-[32,72]">Responsive baslik</h1>
<div class="clamp-p-[16,32]">Responsive padding</div>
<div class="clamp-gap-[8,24]">Responsive gap</div>
<div class="clamp--mt-[20,40]">Negative margin top</div>

<div class="clamp-py-[1024,20,1920,60]">1024px'de 20px, 1920px'de 60px</div>

Yeni: Değerlerde px veya rem kullanılabilir.

<h1 class="clamp-text-[2rem,4rem]">Rem destekli</h1>
<div class="clamp-p-[16px,32px]">Px destekli</div>

Notlar:

• Üretilen clamp sınıfları Tailwind uyumu için @layer utilities içinde yazılır.
• space-x/space-y ve blur clamp map’inden çıkarıldı (Tailwind davranışıyla uyumsuzdu).
• En hızlı kullanım için virtual: true önerilir. Bu durumda CSS dosyası yazılmaz, @import "virtual:penta-clamp.css"; ile direkt Vite üzerinden enjekte edilir.
• Dosyaya yazmak istersen virtual: false ve outputPath kullanabilirsin.

Örnek (dosyaya yazma modu):

clampGeneratorPlugin({
  srcDir: "./src",
  outputPath: "./src/style/generated/clamp.css",
  filePattern: [".hbs", ".html"],
  layer: true,
  cache: true,
  virtual: false
})

Tailwind Variant'lari

<div class="toggle:opacity-100">Toggle class</div>
<div class="visible:opacity-100 opacity-0">Visible class</div>
<div class="starting:opacity-0 opacity-100">Starting style</div>

Not: group-toggle/peer-toggle ve group-visible/peer-visible varyantları artık yalnızca matchVariant ile çalışır (Tailwind’in group/* ve peer/* modeline tam uyum için).

JS Utilities

Not: Tüm data-* attribute'ları netleştirilmiştir. Yeni isimler: data-click-trigger, data-click-target, data-click-args, data-phone-format, data-phone-code, data-tip-success vb.

import {
  scroll,
  phone,
  inview,
  toggle,
  copy,
  smart,
  mask,
  date,
  parallax,
  fx,
} from "penta-pack";

scroll();
phone();
inview();
toggle();
copy();
smart();
mask();
date();
parallax();
fx();

toggle

Popup, modal, dropdown ve toggle islemleri icin guclu bir sistem.

Temel Kullanim:

<!-- Trigger Button -->
<button data-click-trigger="menu" data-click-args="self target">Toggle</button>

<!-- Target Element -->
<nav data-click-target="menu" class="hidden toggle:block">Menu content</nav>

Args (data-click-args) Parametreleri:

| Parametre | Aciklama | |-----------|----------| | self | Trigger elementine toggle class ekler | | target | Target elementlere toggle class ekler | | group | Ayni gruptaki diger itemlari kapatir | | always-open | Sadece class ekler, kaldirmaz | | body-lock | Body'ye overflow-hidden ekler | | esc | ESC tusu ile kapatir | | outside | Disari tiklayinca kapatir | | class:myclass | Ozel toggle class kullanir (default: toggle) |

Popup Ornekleri:

<!-- Modal Popup -->
<button
  data-click-trigger="my-modal"
  data-click-args="target esc outside body-lock"
>
  Modal Ac
</button>

<div
  data-click-target="my-modal"
  class="fixed inset-0 opacity-0 invisible toggle:opacity-100 toggle:visible"
>
  <div class="backdrop" data-click-trigger="my-modal" data-click-args="target"></div>
  <div class="content">Modal icerigi</div>
</div>

<!-- Dropdown -->
<div class="relative">
  <button data-click-trigger="dropdown" data-click-args="self target outside">
    Dropdown
  </button>
  <div
    data-click-target="dropdown"
    class="absolute hidden toggle:block"
  >
    Dropdown content
  </div>
</div>

<!-- Sidebar/Drawer -->
<button data-click-trigger="sidebar" data-click-args="target esc outside body-lock">
  Menu
</button>
<aside
  data-click-target="sidebar"
  class="fixed right-0 translate-x-full toggle:translate-x-0"
>
  Sidebar content
</aside>

JS API:

import { toggle } from "penta-pack";

toggle(); // Initialize

// Programmatic control intentionally omitted (single export)

fx

Gorsel, video, PDF ve galeri icin lightbox/popup sistemi.

Temel Kullanim:

<!-- Tek Gorsel -->
<a href="image-large.jpg" data-fx>
  <img src="image-thumb.jpg" alt="..." />
</a>

<!-- Galeri/Carousel -->
<a href="image1.jpg" data-fx="gallery-1">Gorsel 1</a>
<a href="image2.jpg" data-fx="gallery-1">Gorsel 2</a>
<a href="image3.jpg" data-fx="gallery-1">Gorsel 3</a>

<!-- PDF -->
<a href="document.pdf" data-fx data-fx-type="pdf">PDF Goruntule</a>

<!-- Video -->
<a href="video.mp4" data-fx data-fx-type="video">Video</a>

<!-- YouTube -->
<a href="https://www.youtube.com/watch?v=VIDEO_ID" data-fx>YouTube</a>

<!-- Vimeo -->
<a href="https://vimeo.com/VIDEO_ID" data-fx>Vimeo</a>

Data Attributes:

| Attribute | Aciklama | |-----------|----------| | data-fx | Fancybox'i etkinlestirir. Galeri icin ayni deger kullanin | | data-fx-src | href yerine kaynak URL | | data-fx-type | Medya tipi: image, video, pdf, youtube, vimeo | | data-fx-caption | Alt yazi | | data-fx-thumb | Thumbnail URL | | data-fx-download | "true" ise indirme butonu gosterir |

Ozellikler:

• Carousel/galeri gorunumu
• Tek gorsel popup
• PDF goruntuleyici
• Video oynatici (MP4, WebM, YouTube, Vimeo)
• Indirme butonu
• Zoom (yakinlastirma/uzaklastirma)
• Fullscreen modu
• Thumbnail strip
• Klavye navigasyonu (sol/sag ok, ESC)
• Touch/swipe destegi
• Caption/alt yazi

JS API:

import { fx } from "penta-pack";

// Initialize
fx();

// veya options ile
fx({
  closeOnEsc: true,
  closeOnOutsideClick: true,
  showDownload: false,
  showZoom: true,
  showFullscreen: true,
  showCounter: true,
  zoomLevel: 2,
  loop: true,
  keyboard: true,
  touch: true
});

// Programmatic control removed (single export)

phone

<input type="tel" placeholder="0 (5XX) XXX-XXXX" />
<input
  type="tel"
  data-phone-format="international"
  data-phone-code="+90"
  placeholder="+90 5XX XXX XXXX"
/>
<input type="tel" data-phone-format="plain" placeholder="05XXXXXXXXX" />
<input
  type="tel"
  data-phone-format="us"
  data-phone-code="+1"
  placeholder="+1 (XXX) XXX-XXXX"
/>

date

<input type="date" data-date data-date-lang="tr" />

Not: Popup icinde yil secimi bulunur. Dil icin data-date-lang="tr|en" kullanilabilir.

copy

<button data-copy data-copy-content="Merhaba">Kopyala</button>
<button
  data-copy
  data-tip-pos="right"
  data-tip-duration="2000"
>
  Sag Tooltip
</button>
<button
  data-copy
  data-tip-success="Basarili"
  data-tip-error="Hata"
  data-tip-color="#22c55e"
>
  Ozel Metin
</button>

parallax

<div data-parallax="0.3">Yavas</div>
<div data-parallax="-0.2">Ters</div>
<div data-parallax="0.4" data-parallax-direction="horizontal">Yatay</div>
<div data-parallax="0.3" data-parallax-scale="1.2">Scale</div>

Handlebars Helper'lari

• object, array, concat
• times, for
• even, odd, eq, or
• variable
• counterDigits
• buildVersion, multiply

counterDigits Kullanimi

Sayac animasyonu icin digit HTML'i uretir. data-inview="animate once" ile element gorununce animasyon tetiklenir.

{{#each counter as |item|}}
  <div data-fx-text-counter data-inview="animate once" class="group/item" data-value="{{item.value}}">
    <div class="clamp-text-[20-68]">
      {{{counterDigits item.value}}}
    </div>
    <p class="clamp-text-[12-18]">{{item.label}}</p>
  </div>
{{/each}}

Not: counterDigits HTML dondurur. Triple mustache {{{...}}} kullanin.

Paket Export'lari

export {
  clampGeneratorPlugin,
  generateClampCSS,
  getDefaultPropertyMap,
  createAssetsFixPlugin,
  createVitePresets,
  getOptimizeDepsPreset,
  loadPages,
  loadJsonData,
  getBuildVersion,
  getBuildKey,
  createBuildOutput,
  incrementBuildVersion,
  createHandlebarsHelpers,
  pentailPlugin,
  propertyMap,
  defaultSettings,
  scroll,
  phone,
  inview,
  toggle,
  copy,
  smart,
  mask,
  date,
  parallax,
  fx,
};

Script'ler

npm run build
npm run build:js
npm run build:css

Lisans

MIT