@tecof/app-ui
v0.1.0
Published
Tecof partner uygulamalarının ortak tasarım kimliği: React Suite 6 + Tailwind CSS 4 + lucide-react bileşenleri, form/doğrulama ve sunucu-güvenli şema.
Maintainers
Readme
@tecof/app-ui
Tecof partner uygulamalarının ortak tasarım kimliği: React Suite 6 + Tailwind CSS 4 + lucide-react üzerine
panelle (tecof-app-frontend) aynı görsel dil — Tecof lime imza rengi, zinc nötrler, Geist, rounded-2xl kartlar,
açık/koyu tema (App Bridge'den), tr/en metinler, React Suite Form + paylaşılan şema ile doğrulama.
| Giriş | Ortam | İçerik |
|---|---|---|
| @tecof/app-ui | İstemci ("use client" derlemede eklenir) | TecofAppProvider, kabuk/yerleşim, durum, tablo, form bileşenleri, useAppToast, useAppConfirm |
| @tecof/app-ui/schema | Sunucu-güvenli (React/DOM yok) | createModel, v kuralları, validateOnServer, VKN/TCKN/IBAN/telefon doğrulayıcıları, durum sözlüğü, biçimlendiriciler |
| @tecof/app-ui/styles.css | Tailwind v4 CSS | Tema belirteçleri, React Suite → Tecof değişkenleri, @source |
Bağımlılıklar (peer): react ^19, react-dom ^19, rsuite ^6.2, lucide-react, @tecof/app-bridge ^0.1.
Çalışma zamanı bağımlılığı yalnız schema-typed (React Suite'in kendi şema kütüphanesi; sunucu girişi için).
Kurulum
npm i @tecof/app-ui @tecof/app-bridge rsuite lucide-react geist
npm i -D tailwindcss @tailwindcss/postcssnpm'de yayınlanana kadar: package.json'a "@tecof/app-ui": "^0.1.0" yazın, diğer bağımlılıkları normal kurun,
sonra tarball'ı kaydetmeden ekleyin — npm install <tgz> file: yolunu package.json/lockfile'a yazar, lockfile'a
yol girmemeli:
npm install --no-save ../tecof-app-sdk/.artifacts/tecof-app-ui-0.1.0.tgz # tecof-app-sdk: npm run pack:localpostcss.config.mjs: export default { plugins: { "@tailwindcss/postcss": {} } };
app/globals.css — sıra önemli, başka CSS ekleme:
@layer theme, base, rsuite, components, utilities;
@import "tailwindcss";
@import "rsuite/dist/rsuite-no-reset.min.css" layer(rsuite);
@import "@tecof/app-ui/styles.css";app/layout.tsx:
import type { Metadata, Viewport } from "next";
import { GeistSans } from "geist/font/sans";
import { GeistMono } from "geist/font/mono";
import { Providers } from "./providers";
import "./globals.css";
export const metadata: Metadata = { title: "Uygulamam", robots: { index: false, follow: false } };
export const viewport: Viewport = { width: "device-width", initialScale: 1 };
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="tr" data-theme="light" suppressHydrationWarning className={`${GeistSans.variable} ${GeistMono.variable}`}>
<body>
<Providers>{children}</Providers>
</body>
</html>
);
}(next/font/google ile Geist({ variable: "--font-geist-sans" }) da olur; kit --font-geist-sans / --font-geist-mono
değişkenlerini okur.)
app/providers.tsx:
"use client";
import { TecofAppProvider } from "@tecof/app-ui";
export function Providers({ children }: { children: React.ReactNode }) {
// App Bridge'i kendisi kurar (dışarıda <AppBridgeProvider> varsa onu kullanır), tema/dili panelden alır,
// <html data-theme class="dark" lang> ayarlar, toast/onay köprüsünü sağlar.
return <TecofAppProvider>{children}</TecofAppProvider>;
}Panel dışında geliştirmek için allowStandalone (köprü null, toast/onay React Suite'le çalışır) ya da
bridge="off" theme="dark" locale="en".
Kabuk ve ekranlar
"use client";
import Link from "next/link";
import { usePathname } from "next/navigation";
import { AppShell, StatusBadge } from "@tecof/app-ui";
import { FileText, LayoutDashboard, ScrollText, Settings } from "lucide-react";
export function Shell({ children }: { children: React.ReactNode }) {
const pathname = usePathname();
return (
<AppShell
title="Logo İşbaşı"
subtitle="e-Fatura / e-Arşiv"
icon={<FileText />}
status={<StatusBadge status="connected" />}
linkAs={Link}
activeHref={pathname}
tabs={[
{ href: "/", label: "Genel bakış", icon: <LayoutDashboard /> },
{ href: "/invoices", label: "Faturalar", icon: <ScrollText /> },
{ href: "/settings", label: "Ayarlar", icon: <Settings /> },
]}
>
{children}
</AppShell>
);
}Bileşenler: PageHeader, Section (başlık/açıklama/eylem/alt bilgi; tablo ve form için padded={false}),
StatGrid + StatCard, EmptyState, StatusBadge, Callout (React Suite Message), KeyValueList,
CopyValue, DataTable (React Suite Table; yükleniyor/boş + 640 px altı kart görünümü), LogList,
ConfirmButton (panelde App Bridge onayı). Simge propları eleman alır (icon={<Receipt />}), böylece
sunucu bileşenlerinden de kullanılabilir. AppShell'e linkAs={Link} geçmek için onu bir istemci bileşeninde
kullanın.
DataTable: uzun metin sütununatruncate: true(tek satır, üç nokta, tam metintitle'da); kendirender'ınızda<span className="block truncate">de üç noktayla kesilir. Diğer hücreler satıra sığacak şekilde kaydırılır; web fontu sonradan yüklenince satır yükseklikleri yeniden ölçülür. Boş listede tablo yerineempty(varsayılanEmptyState) doğal yüksekliğinde gösterilir; yüklenirken tablo başlığı + yükleniyor kalır.PageHeader eyebrowyazıldığı gibi gösterilir (CSS büyük harfi Türkçede "KolayBi" → "KOLAYBİ" yapar). Marka içermeyen etikette büyük harf istersenizeyebrowCase="upper". Marka adlarınauppercasesınıfı vermeyin.
Durum sözlüğü
StatusBadge status="…" tek sözlükten ton + tr/en etiket alır: success · warning · error · info · neutral ·
pending, fatura (creating · draft · issued · signed · failed · skipped · needs-cancellation · deleted · cancelled),
gönderim (queued · processing · sending · sent · delivered · undelivered · rejected), kargo (label-created ·
shipped · in-transit · out-for-delivery · returned), bağlantı/abonelik (connected · disconnected ·
not-configured · active · inactive · trialing · past_due · expired). Sunucuda statusTone/statusLabel
(@tecof/app-ui/schema).
Formlar — tek şema, iki taraf
// lib/settings-model.ts (paylaşılan; "use client" YOK)
import { createModel } from "@tecof/app-ui/schema";
export type Settings = { companyName: string; email: string; vkn: string; mode: string; apiKey: string };
export const settingsModel = createModel<Settings>((v, ctx) => ({
companyName: v.text({ required: true, max: 120 }),
email: v.email({ required: true }),
vkn: v.vknOrTckn(),
mode: v.select(["draft", "live"], { required: true }),
apiKey: v.secret({ required: !ctx.secrets.apiKey }), // kayıtlıysa boş = değiştirme
}));// app/settings/settings-form.tsx
"use client";
import { useState } from "react";
import { AppForm, FormActions, Section, SecretField, SelectField, TextField, useAppToast } from "@tecof/app-ui";
import { readFieldErrors } from "@tecof/app-ui/schema";
import { useSessionFetch } from "@tecof/app-bridge/react";
import { settingsModel, type Settings } from "@/lib/settings-model";
export function SettingsForm({ initial, apiKey }: { initial: Settings; apiKey: { set: boolean; last4?: string } }) {
const [value, setValue] = useState(initial);
const [saved, setSaved] = useState(initial);
const fetch = useSessionFetch();
const toast = useAppToast();
return (
<AppForm
model={settingsModel}
modelContext={{ secrets: { apiKey: apiKey.set } }}
formValue={value}
initialValue={saved}
onChange={setValue}
onSubmit={async (data) => {
const res = await fetch("/api/settings", { method: "PUT", headers: { "content-type": "application/json" }, body: JSON.stringify(data) });
const json = await res.json().catch(() => ({}));
if (!res.ok) return { errors: readFieldErrors(json), message: json.message };
setSaved({ ...data, apiKey: "" });
setValue({ ...data, apiKey: "" });
toast.success("Ayarlar kaydedildi");
}}
>
<Section title="Bağlantı" description="Sağlayıcı hesabınız" padded={false}>
<TextField name="companyName" label="Firma adı" />
<TextField name="email" label="E-posta" type="email" />
<TextField name="vkn" label="VKN / TCKN" inputMode="numeric" />
<SelectField name="mode" label="Mod" options={[{ label: "Taslak", value: "draft" }, { label: "Canlı", value: "live" }]} />
<SecretField name="apiKey" label="API anahtarı" stored={apiKey} />
</Section>
<FormActions />
</AppForm>
);
}// app/api/settings/route.ts
import { validateOnServer, resolveLocale } from "@tecof/app-ui/schema";
import { settingsModel } from "@/lib/settings-model";
export async function PUT(request: Request) {
const session = tecof.sessionFromRequest(request); // @tecof/app-sdk
const stored = await listSecretKeys(session.installationId); // Vault: [{ key }]
const result = validateOnServer(settingsModel, await request.json().catch(() => null), {
locale: resolveLocale(session.locale),
context: { secrets: { apiKey: stored.includes("apiKey") } },
});
if (!result.ok) return result.response(); // 422 { error, message, fields }
// result.value: yalnız şema alanları, metinler kırpılmış, sayılar çevrilmiş. apiKey "" → değiştirme.
}Hazır alanlar: TextField, TextareaField, NumberField, SelectField (SelectPicker block, 8+ seçenekte
aranabilir), ToggleField, CheckboxGroupField, RadioField, PasswordField, SecretField, genel Field
(accepter={DatePicker} vb.). Girdi öznitelikleri (inputMode, autoComplete, maxLength, minLength, pattern,
spellCheck, autoCapitalize, autoFocus, enterKeyHint, data-*) <input>/<textarea>'nın kendisine geçer — TextareaField, PasswordField
ve SecretField dahil (React Suite PasswordInput bunları sarmalayıcıya verdiği için kit kendi PasswordBox'ını kullanır).
AppFormgönderimdeformRef.check()çalıştırır; hatalıysaonCheckFail(errors, "client")(odaklanmadan ÖNCE — katlanmış satırı/sekmeyi burada açın), uyarı toast'ı ve ilk hatalı alana odak. Sunucu{ errors }dönerseonCheckFail(errors, "server"). Formun içindenuseAppForm()→{ errors, saving, dirty, submit, reset, … }.layout="stack"çekmece/modal içindir.FormActions: varsayılan Kaydet + geri al (mobilde değişiklik varken alta yapışık). Gönderme formları içinsubmitLabel="Gönder" submittingLabel="Gönderiliyor…" submitIcon={<Send className="size-4" />} hideCancel, önkoşul eksiksedisabled. Formun ortasında tek düğme:<SubmitButton icon={…} submittingLabel="…">Gönder</SubmitButton>.SecretField stored={{ set, last4?, display?, updatedAt? }}: rozetdisplay(sunucunun ürettiği maske, ör."850*****03") ya da••••last4gösterir; sır hiçbir zaman istemciye gelmez.
Kurallar (v, tr; createRules("en")): text({required,min,max,pattern,trim}) (trim: false → sunucuda
kırpılmaz; SMS/şablon gövdesi), email, httpsUrl({hosts}), trMobile, e164Phone, vkn, tckn, vknOrTckn,
iban (TR, mod-97), number({min,max,integer}), boolean({mustBeTrue}), select(values),
multiSelect(values,{min,max}), secret({required,min,max}), custom(check, message, {required, priority}).
Koşullu zorunluluk: her kural requiredIf: (form) => boolean alır (v.httpsUrl({ requiredIf: (d) => d.mode === "live" }));
boş değerde de çalışır ve Field yıldızı güncel form değeriyle bunu gösterir. Koşulu belirleyen alana
.proxy(["bağımlı-alan"]) ekleyin ki değişince bağımlı alan yeniden denetlensin. schema-typed .when() gibi kitin
okuyamadığı koşullarda yıldız için Field/hazır alana required={(value) => value.mode === "live"} verin.
isFieldRequired(type, formValue) (sunucu girişi) aynı hesabı yapar.
Özel kural: v.custom((value: unknown, data?: MyForm) => …, "mesaj") — değer/form verisi tipleri geri çağırmadan
çıkar. Ham schema-typed kullanacaksanız dikkat: MixedType<A, B>() fabrikasında A = değer tipi, B = form verisi
tipi (adları yanıltıcı); bunun yerine mixedOf<Değer, FormVerisi>() kullanın (aynı nesne, adlı genel parametreler).
Türkiye cep telefonu: parseTrMobile(x) → { ok: true, national: "5XXXXXXXXX", e164: "+905XXXXXXXXX" } ya da
{ ok: false, reason: "missing" | "invalid" | "not-tr" | "not-mobile" }. Harf içeren değer reddedilir ("… dahili 12");
+90 / 0090 / 90 / 0 önekleri, boşluk, tire, nokta, parantez kabul ("+90 (0532) 111 22 33", "9005321112233").
normalizeTrMobile (→ +905… | null), isTrMobile, v.trMobile() aynı kuralı kullanır (tecof-app-netgsm
lib/phone.ts ile 1200+ girdide aynı sonuç). Günlükte maskTrMobile(x) → "0532 *** ** 33".
Diğer saf yardımcılar: isVkn, isTckn, isTrIban, normalizeIban, isE164Phone, isHttpsUrl(url, hosts),
maskSecret, formatDateTime (Europe/Istanbul), formatMoney.
Geliştirme
npm run build -w @tecof/app-ui # tsup: index ("use client") + schema (sunucu) ESM/CJS + d.ts
node --test packages/app-ui/test/*.test.mjsGörsel galeri: packages/app-ui/examples/gallery (yayınlanmaz).
