Bileşenler

sitelo-ui, sitelo için bir bileşen kitaplığıdır. Her bileşen bir HTML dizesi döndüren bir fonksiyondur, bu yüzden arada hiçbir şey olmadan doğrudan bir javascript-to-html ağacına yerleşir — derleyici yok, çalışma zamanı yok, hidrasyon yok. Ne kurarsanız dist/ içine o iner.

sitelo ile birlikte, sitelo/ui giriş noktası altında gelir.

Hızlı başlangıç

npm install sitelo javascript-to-html

styles() işlevini head içine koyun ve bileşenleri body içinde çağırın. Kurulumun tamamı bu kadar:

import { body, head, html, meta, title } from 'javascript-to-html'
import { styles, container, stack, heading, text, button } from 'sitelo/ui'

export default () => html({ lang: 'tr' },
  head(
    meta({ charset: 'utf-8' }),
    meta({ name: 'viewport', content: 'width=device-width, initial-scale=1' }),
    title('Sitem'),
    styles(),
  ),
  body(
    container({ size: 'md' },
      stack({ gap: 'md' },
        heading({ level: 1 }, 'Merhaba'),
        text({ variant: 'lead' }, 'Bileşenlerden kurulmuş bir sayfa.'),
        button({ href: '/docs' }, 'Belgeleri oku'),
      ),
    ),
  ),
)

Bileşen adları bilerek işledikleri şeyle eşleşir; bu da birkaçının — button, input, table, link, code, select, progress — javascript-to-html’in öğe fonksiyonlarıyla çakışması demektir. İkisine birden ihtiyacınız olduğunda kitaplığı bir ad alanı olarak içe aktarın:

import * as ui from 'sitelo/ui'

ui.card(
  ui.cardHeader({ title: 'Yönlendirme', subtitle: 'Dosya tabanlı' }),
  ui.cardBody(ui.text('src/about.ht.js /about olur.')),
  ui.cardFooter({ divided: true }, ui.button({ size: 'sm' }, 'Devamını oku')),
)

Çağırma kuralı

Her bileşen, tıpkı bir javascript-to-html öğesi gibi, isteğe bağlı bir prop nesnesi ve ardından çocuklar alır. Bileşenin anladığı proplar ada göre tüketilir; geri kalan her şey işlenen öğeye öznitelik olarak düşer, böylece id, data-*, aria-* ve olay öznitelikleri kitaplığın onları listelemesine gerek kalmadan çalışır:

button({ id: 'save', 'data-analytics': 'save-click', onclick: 'save()' }, 'Kaydet')
// <button type="button" id="save" data-analytics="save-click" onclick="save()" class="su-btn …">

Bileşenin değerini tanımadığı bir prop — variant: 'nonsense' — hata fırlatmak yerine varsayılana geri döner. Görünüşe dair bir yazım hatası bir derlemeyi düşürmemeli.

Biçimlendirme

styles(), tarayıcının sayfalar arasında önbelleğe aldığı tek bir dosyaya bir <link> döndürür; sitelo’nun eklentisi onu geliştirmede sunar ve derlemeye, immutable olarak sunabileceğiniz, içerik özetli bir adla yazar. { inline: true } bunun yerine bütün sayfayı tutan bir <style> döndürür — hat üzerinde yaklaşık 11 kB, fazladan istek yok ve dist/ içinden kaybolabilecek hiçbir şey yok:

import { styles } from 'sitelo/ui'

head(
  // tüm stil sayfası sayfanın içinde — hiç istek yok
  styles({ inline: true }),
)

Sayfa kitaplıktaki her bileşeni kapsar, bir site ise bir avuç kullanır. sitelo.config.js içindeki pruneCss: true yalnızca derlemenin eşleştirebildiği kuralları yazar: eklenti, henüz yazdığı sayfalardan — ve bir bildirim ya da bir adımın sonradan eklediği sınıflar için yanlarındaki betiklerden — su- sınıflarını okur ve seçicisi hiçbir şeyin taşımadığı bir sınıfı adlandıran her kuralı atar. İçe aktarmalardan değil çıktıdan karara bağlanır, bu yüzden button({ variant: 'soft' }) ifadesi .su-btn--soft kuralını korur, düz bir button() ise korumaz. Bağlanmış bir sayfa bütün siteye karşı budanır ve yeni bir özet alır, her <link> buna göre yeniden yazılır; satır içine alınmış olan ise kendi sayfasına budanır. Bir düzine bileşen gzip ile 2–3 kB eder. Geliştirme sayfanın tamamını sunar; bir sunucu adasınınki gibi derlemenin hiç görmediği biçimlendirmenin sınıflarının keep içinde adlandırılması gerekir:

export default {
  pruneCss: true,
  // ya da derlemenin hiç görmediği sınıfları yaz; önek için `*`
  // pruneCss: { keep: ['su-card', 'su-btn*'] },
}

Temalar

Her şey :root üzerindeki CSS özel özellikleriyle sürülür — beş palet, bir boşluk ölçeği, yarıçaplar, yazı ve gölgeler. theme() onlar için geçersiz kılmalar yazar ve camelCase adları (radiusMd → --su-radius-md), palet nesnelerini ya da düz özel özellikleri alır:

import { styles, theme } from 'sitelo/ui'

head(
  styles(),
  // styles() sonrası, böylece bunlar kazanır.
  theme({
    primary: { base: '#5b5bd6', hover: '#4a4ac4', fg: '#ffffff' },
    radiusMd: '2px',
    fontSans: '"Inter", system-ui, sans-serif',
  }, {
    dark: { primary: { base: '#8f8ff0' } },
  }),
)

Koyu kip kendi başına prefers-color-scheme değerinden çözülür. Herhangi bir atada data-theme ya da data-su-theme özniteliğini light veya dark yapmak bunu geçersiz kılar — themeToggle() de tam olarak bunu yapar:

import { styles, themeScript, themeToggle } from 'sitelo/ui'

head(
  themeScript(), // kayıtlı seçimi ilk boyamadan önce uygular
  styles(),
)

// …body içinde herhangi bir yerde
themeToggle()

Bütün görünümü tek seferde değiştirmek de mümkün: styles({ preset: 'neumorphism' }) bir hazır ayarın stil sayfasını çekirdek stil sayfasının hemen ardından bağlar, her bileşen onu izler ve theme() üstünde çalışmayı sürdürür. Neumorfizm sayfasında canlı olarak görülebilir.

JavaScript ve ne kadar azı olduğu

Çoğu bileşenin hiç ihtiyacı yok. Kip ve çekmece birer popover öğesidir, bu yüzden açılmayı, arka planı, dışarı tıklamayı ve Escape’i tarayıcı halleder. Akordeon <details name> öğesidir. Menüler <details> öğesidir. İpuçları CSS’tir. Panelleri yerinde değişen sekmeler bir radyo grubudur: her sekme bir <label> ve işaretli radyonun ardından gelen panel, CSS’in gösterdiği paneldir.

Üç şey bir betik ister ve her biri kendi betiğini kendisi alır:

• kapatılabilir bir uyarıdaki kapatma düğmesi
• bir menüyü dışarı tıklamada ya da Escape ile kapatmak
• tema değiştirici

Giriş dosyanıza eklenecek bir şey yok — içe aktarma, olay özniteliğinin kendisi:

<!-- rendered by alert({ dismissible: true }) -->
<button class="su-alert-dismiss"
        onclick="import('/su/alert.js').then(m=>m.dismiss(this))">
  &times;
</button>

sitelo siz geliştirirken bu modülleri /su/ altından sunar ve sayfalarınızın gerçekten başvurduklarını derlemeye kopyalar. Her biri bir kilobaytın epey altındadır, hiçbiri ilk etkileşimden önce getirilmez ve o ana dek her bileşen doğru işlenir: menüler kendi başlarına açılıp kapanır, kapatma düğmesi bir şey yapmaz.

İstisna toast(), çünkü sayfadaki hiçbir şey onu sizin için tetiklemez:

// src/main.js
import { toast } from 'sitelo/ui/client'

Örnekler

Formlar kendi etiketlerini, kimliklerini, yardım metinlerini ve hata iletilerini kendileri bağlar:

import { card, cardBody, cardFooter, button, stack, textField, selectField } from 'sitelo/ui'

card(
  cardBody(
    stack({ gap: 'md' },
      textField({ label: 'E-posta', name: 'email', type: 'email', help: 'Asla paylaşılmaz.' }),
      textField({ label: 'Site', name: 'site', startAdornment: 'https://', error: 'Bir URL değil.' }),
      selectField({ label: 'Plan', name: 'plan', options: ['Ücretsiz', 'Pro'], value: 'Pro' }),
    ),
  ),
  cardFooter({ divided: true }, button({ type: 'submit' }, 'Kaydet')),
)

Bir kip popover’dır ve tetikleyicisi kimliğini gösteren herhangi bir düğmedir:

import { button, modal } from 'sitelo/ui'

button({ popovertarget: 'confirm' }, 'Sil…')

modal({
  id: 'confirm',
  title: 'Bu sayfa silinsin mi?',
  footer: button({ color: 'danger' }, 'Sil'),
}, 'Bu geri alınamaz.')

Sekmeler iki biçimde gelir — bağlantılar ya da paneller:

// Bağlantı sekmeleri: sekme başına bir sayfa, hiç script yok.
tabs({ items: [
  { label: 'Belgeler', href: '/docs', active: true },
  { label: 'API', href: '/api' },
] })

// Panel sekmeleri: yerinde değişir, bir radyo grubu ve CSS ile.
tabs({ value: 'use', items: [
  { id: 'install', label: 'Kurulum', panel: code('npm install sitelo') },
  { id: 'use', label: 'Kullanım', panel: code("import * as ui from 'sitelo/ui'") },
] })

Tablolar columns ve rows alır; bir hücre bir değerden fazlasını gerektirdiğinde yanına bir render fonksiyonu gelir:

table({
  striped: true,
  columns: [
    { key: 'page', header: 'Sayfa' },
    { key: 'size', header: 'Boyut', align: 'end' },
    { header: 'Durum', render: (row) => chip({ color: row.ok ? 'success' : 'danger' }, row.ok ? 'ok' : 'başarısız') },
  ],
  rows: pages,
})

Depodaki examples/ui dizini her bileşeni tek bir sayfada işler — bütün seti görmenin en hızlı yolu budur.

Bileşen başvurusu

Gruba göre her dışa aktarım. Proplar türlenmiştir: sitelo/ui .d.ts dosyalarıyla gelir, bu yüzden bir düzenleyici variant, color ve size değerlerini TypeScript’te olduğu gibi JavaScript’te de sizin için tamamlar.

İki ad beklediğinizden farklıdır: anahtar toggle adını taşır, çünkü switch ayrılmış bir sözcüktür ve bir içe aktarma bağı olamaz; biçimlendirilmiş bağlantı ise hem link hem textLink olarak dışa aktarılır, böylece javascript-to-html’in link fonksiyonunun yanında durabilir. table, input, select ve progress aynı kaçış kapısına sahiptir: dataTable, textInput, selectField, progressBar.

Ekstralar

İkinci bir giriş noktası olan sitelo/ui-extras, herkese göre olmayan bileşenleri barındırır — dokular ve efektler, başlangıç olarak bir film grenli. Her biri kendi stil sayfasını getirir, styles() yanında grainStyles(), böylece bir sayfa yalnızca kullandığını bağlar; sitelo/ui-extras/client ise onların sayfa tarafındaki çağrılarını taşır. Hepsi sitelo UI ekstralarında kataloglanmıştır.