@konce-pt/theme 0.9.0

package/dist/emit.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Emitery motywu. Każdy bierze dokument i zwraca tekst pliku — nic nie zapisuje i nic nie wie
+ * o systemie plików, bo edytor działa w przeglądarce.
+ *
+ * Jedna zasada wiąże je wszystkie z podglądem: podgląd wstrzykuje **dokładnie ten tekst**, który
+ * zwraca `emitCss`. Nie „równoważny" — ten sam. Narzędzie, którego podgląd rozjeżdża się
+ * z artefaktem, nie ma racji bytu.
+ */
+import type { KptTokenMap } from './resolve.ts';
+import type { KptThemeDoc, KptThemeMode } from './schema.ts';
+export interface KptEmitOptions {
+    /** Selektor motywu ciemnego. Domyślnie ten, którego używa biblioteka. */
+    darkSelector?: string;
+    /** Dołóż blok `@media (prefers-color-scheme: dark)` — biblioteka sama go nie ma. */
+    prefersColorScheme?: boolean;
+    /** Patrz `KptThemeExport.compat`. */
+    compat?: 'resolved' | 'layered';
+    /** Wyemituj komplet tokenów zamiast różnicy. Do podglądu całości i do diagnostyki. */
+    complete?: boolean;
+}
+/**
+ * Co trafia do pliku, dla jednego motywu.
+ *
+ * `resolved` (domyślne) emituje **całą różnicę wartościami dosłownymi**, prymitywy w to wliczając,
+ * i powtarza je w obu blokach. Powtarzanie nie jest marnotrawstwem: w wersjach `@konce-pt/tokens`
+ * sprzed poprawki `tokens.dark.css` deklarował komplet prymitywów wewnątrz `[data-theme="dark"]`,
+ * więc nadpisanie prymitywu w samym `:root` działało w motywie jasnym, a w ciemnym było po cichu
+ * przebijane. Blok ciemny idący później wygrywa z nim kolejnością i plik zachowuje się tak samo
+ * na każdej wersji biblioteki.
+ *
+ * Prymitywów **nie wolno pomijać**, choć kusi to przy kolorach: warstwa semantyczna niesie cały
+ * kolor, ale nie niesie typografii ani odstępów. Żaden token nie powołuje się na `--kpt-font-size-*`
+ * — komponenty czytają je wprost w swoich regułach — więc plik bez prymitywów gubiłby zmianę kroju
+ * i skali pisma w całości. Przy promieniach szkoda byłaby częściowa i przez to gorsza: sześć
+ * tokenów komponentowych powołuje się na `--kpt-radius-*`, więc część rogów by się zmieniła,
+ * a część nie.
+ *
+ * `layered` emituje prymitywy raz, w `:root`, i tylko te tokeny, których wartości **nie** tłumaczy
+ * już kaskada po nich — plik krótszy i czytelniejszy, ale wymagający wersji biblioteki z poprawką
+ * ciemnego arkusza.
+ */
+export declare function emitPlan(doc: KptThemeDoc, mode: KptThemeMode, options?: KptEmitOptions): KptTokenMap;
+/**
+ * Arkusz motywu. Blok ciemny emitujemy **zawsze**, nawet identyczny z jasnym: bez niego
+ * `data-theme="dark"` po cichu wraca do wartości stockowych, a to jest najtrudniejszy do
+ * znalezienia rodzaj usterki motywu.
+ */
+export declare function emitCss(doc: KptThemeDoc, options?: KptEmitOptions): string;
+/** Ten sam motyw jako mixiny SCSS — dla konsumentów kompilujących style ze źródeł. */
+export declare function emitScss(doc: KptThemeDoc, options?: KptEmitOptions): string;
+/**
+ * Motyw jako moduł TypeScriptu, razem z funkcją nakładającą go w runtime.
+ *
+ * Plik jest samowystarczalny — zero importów — bo trafia do repozytorium konsumenta, gdzie
+ * `@konce-pt/theme` nie musi być zainstalowany. To jest droga dla aplikacji, w których motyw
+ * wybiera użytkownik końcowy, a nie build.
+ */
+export declare function emitTs(doc: KptThemeDoc, options?: KptEmitOptions): string;
+/**
+ * Eksport w formacie W3C Design Tokens. Tryby jasny i ciemny idą jako dwie grupy najwyższego
+ * poziomu, bo **DTCG nie standaryzuje trybów** — każdy eksporter koduje je inaczej i nie ma
+ * zapisu, który byłby tu „poprawny". Dwie grupy są przynajmniej jednoznaczne i czytelne dla
+ * człowieka, a importer po drugiej stronie i tak wymaga wskazania, co jest czym.
+ *
+ * To jest eksport do narzędzi projektowych, nie synchronizacja.
+ */
+export declare function emitDtcg(doc: KptThemeDoc, options?: KptEmitOptions): string;
+/** Ile tokenów zmienia motyw względem stocku — do podsumowania w interfejsie. */
+export declare function themeSize(doc: KptThemeDoc): {
+    light: number;
+    dark: number;
+    semantic: number;
+};
+/** Wartości stockowe — wystawione, żeby edytor mógł pokazać „wróć do domyślnej". */
+export declare const stockValue: (name: string, mode: KptThemeMode) => string | undefined;
+export declare const rawValue: (name: string, mode: KptThemeMode) => string | undefined;

package/dist/emit.js

@@ -0,0 +1,276 @@
+/**
+ * Emitery motywu. Każdy bierze dokument i zwraca tekst pliku — nic nie zapisuje i nic nie wie
+ * o systemie plików, bo edytor działa w przeglądarce.
+ *
+ * Jedna zasada wiąże je wszystkie z podglądem: podgląd wstrzykuje **dokładnie ten tekst**, który
+ * zwraca `emitCss`. Nie „równoważny" — ten sam. Narzędzie, którego podgląd rozjeżdża się
+ * z artefaktem, nie ma racji bytu.
+ */
+import { isKnownToken, isPrimitiveToken, resolveTheme, stockTheme, themeDiff } from "./resolve.js";
+import { KPT_RAW, KPT_SEMANTIC_TOKENS } from "./generated/tokens.js";
+const DEFAULT_DARK_SELECTOR = '[data-theme="dark"]';
+const SEMANTIC = new Set(KPT_SEMANTIC_TOKENS);
+const optionsOf = (doc, options = {}) => ({
+    darkSelector: options.darkSelector ?? doc.export?.darkSelector ?? DEFAULT_DARK_SELECTOR,
+    prefersColorScheme: options.prefersColorScheme ?? doc.export?.prefersColorScheme ?? false,
+    compat: options.compat ?? doc.export?.compat ?? 'resolved',
+    complete: options.complete ?? false,
+});
+/**
+ * Co trafia do pliku, dla jednego motywu.
+ *
+ * `resolved` (domyślne) emituje **całą różnicę wartościami dosłownymi**, prymitywy w to wliczając,
+ * i powtarza je w obu blokach. Powtarzanie nie jest marnotrawstwem: w wersjach `@konce-pt/tokens`
+ * sprzed poprawki `tokens.dark.css` deklarował komplet prymitywów wewnątrz `[data-theme="dark"]`,
+ * więc nadpisanie prymitywu w samym `:root` działało w motywie jasnym, a w ciemnym było po cichu
+ * przebijane. Blok ciemny idący później wygrywa z nim kolejnością i plik zachowuje się tak samo
+ * na każdej wersji biblioteki.
+ *
+ * Prymitywów **nie wolno pomijać**, choć kusi to przy kolorach: warstwa semantyczna niesie cały
+ * kolor, ale nie niesie typografii ani odstępów. Żaden token nie powołuje się na `--kpt-font-size-*`
+ * — komponenty czytają je wprost w swoich regułach — więc plik bez prymitywów gubiłby zmianę kroju
+ * i skali pisma w całości. Przy promieniach szkoda byłaby częściowa i przez to gorsza: sześć
+ * tokenów komponentowych powołuje się na `--kpt-radius-*`, więc część rogów by się zmieniła,
+ * a część nie.
+ *
+ * `layered` emituje prymitywy raz, w `:root`, i tylko te tokeny, których wartości **nie** tłumaczy
+ * już kaskada po nich — plik krótszy i czytelniejszy, ale wymagający wersji biblioteki z poprawką
+ * ciemnego arkusza.
+ */
+export function emitPlan(doc, mode, options = {}) {
+    return plansOf(doc, options)[mode];
+}
+/** Para planów dla obu motywów. Liczona raz, bo `balance` i tak potrzebuje obu naraz. */
+function plansOf(doc, options = {}) {
+    if (optionsOf(doc, options).complete) {
+        const all = resolveTheme(doc);
+        return { light: { ...all.light }, dark: { ...all.dark } };
+    }
+    return balance(doc, options);
+}
+/**
+ * Oba bloki z **tym samym zestawem kluczy**. To nie jest ozdoba, tylko warunek poprawności.
+ *
+ * Plik motywu ładuje się PO `tokens.dark.css`, a `:root` i `[data-theme="dark"]` mają dokładnie
+ * tę samą specyficzność — przy remisie rozstrzyga kolejność w dokumencie. Nasz `:root` stoi więc
+ * wyżej niż biblioteczne nadpisanie ciemne. Token zmieniony tylko w motywie jasnym i wypisany
+ * w samym `:root` **przecieknąłby do ciemnego**: tam nikt by go już nie przykrył.
+ *
+ * Dlatego dla każdego tokenu, który trafia do jednego bloku, drugi blok dostaje jego własną
+ * wartość — najczęściej stockową, czyli dosłownie przywrócenie tego, co biblioteka i tak miała.
+ * Wygląda na nadmiarowe i takie jest w połowie przypadków; druga połowa to różnica między motywem
+ * działającym a ciemnym, który po cichu przejmuje barwy jasnego.
+ */
+function balance(doc, options = {}) {
+    const plans = {
+        light: planFor(doc, 'light', options),
+        dark: planFor(doc, 'dark', options),
+    };
+    const all = new Set([...Object.keys(plans.light), ...Object.keys(plans.dark)]);
+    const full = resolveTheme(doc);
+    for (const mode of ['light', 'dark']) {
+        for (const name of all) {
+            plans[mode][name] ??= full[mode][name] ?? '';
+        }
+    }
+    return plans;
+}
+function planFor(doc, mode, options = {}) {
+    const resolved = optionsOf(doc, options);
+    const diff = themeDiff(doc, mode);
+    if (resolved.compat === 'resolved')
+        return diff;
+    // Warstwowo: najpierw same prymitywy, potem to, czego one nie wyjaśniają.
+    const primitiveOnly = { kptTheme: doc.kptTheme, overrides: { primitive: {} } };
+    for (const [name, value] of Object.entries(diff)) {
+        if (isPrimitiveToken(name))
+            primitiveOnly.overrides.primitive[name] = value;
+    }
+    const afterPrimitives = resolveTheme(primitiveOnly)[mode];
+    const plan = { ...primitiveOnly.overrides.primitive };
+    for (const [name, value] of Object.entries(diff)) {
+        if (!isPrimitiveToken(name) && afterPrimitives[name] !== value)
+            plan[name] = value;
+    }
+    return plan;
+}
+const sorted = (map) => Object.entries(map).sort(([a], [b]) => a.localeCompare(b));
+const block = (selector, map, indent = '  ') => {
+    const body = sorted(map)
+        .map(([name, value]) => `${indent}${name}: ${value};`)
+        .join('\n');
+    return `${selector} {\n${body}\n}`;
+};
+/**
+ * Nagłówek arkusza — razem z instrukcją ładowania.
+ *
+ * Instrukcja jedzie w komentarzu, a nie w osobnym pliku, bo osobny plik ginie przy pierwszym
+ * skopiowaniu samego arkusza — a arkusz kopiuje się częściej, niż pobiera całą paczkę. Kolejność
+ * jest tu jedyną rzeczą, którą da się zrobić źle bez żadnego komunikatu błędu: plik wczytany przed
+ * `tokens.css` po prostu nic nie robi.
+ */
+const header = (doc) => {
+    const name = doc.meta?.name ? `"${doc.meta.name}" ` : '';
+    const based = doc.meta?.basedOn ? ` · ${doc.meta.basedOn.package} ${doc.meta.basedOn.version}` : '';
+    const stamp = doc.meta?.updatedAt ? ` · ${doc.meta.updatedAt}` : '';
+    return [
+        `/* Koncept UI theme ${name}— ui.konce.pt/theme`,
+        ` * kpt-theme ${doc.kptTheme}${based}${stamp}`,
+        ' *',
+        ' * Load AFTER @konce-pt/tokens/css and @konce-pt/tokens/css/dark.',
+        ' *',
+        ' * Angular CLI — angular.json > styles[], in this order:',
+        ' *     node_modules/@konce-pt/tokens/dist/css/tokens.css',
+        ' *     node_modules/@konce-pt/tokens/dist/css/tokens.dark.css',
+        ' *     node_modules/@konce-pt/styles/index.css',
+        ' *     src/kpt-theme.css        <- this file',
+        ' *     src/styles.scss',
+        " *   Do NOT import it from main.ts — under the CLI that yields an orphaned chunk and no styles.",
+        ' *',
+        ' * Vite / React:',
+        " *     import '@konce-pt/tokens/css';",
+        " *     import '@konce-pt/tokens/css/dark';",
+        " *     import '@konce-pt/styles';",
+        " *     import '@konce-pt/styles/components';   // React only — this is what styles kpt-*",
+        " *     import './kpt-theme.css';               // last one wins",
+        ' *',
+        ' * Dark mode is an attribute on the root element and the library does not read',
+        ' * prefers-color-scheme — the application sets it:',
+        ' *     document.documentElement.dataset.theme =',
+        " *       matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';",
+        ' */',
+    ].join('\n');
+};
+/**
+ * Arkusz motywu. Blok ciemny emitujemy **zawsze**, nawet identyczny z jasnym: bez niego
+ * `data-theme="dark"` po cichu wraca do wartości stockowych, a to jest najtrudniejszy do
+ * znalezienia rodzaj usterki motywu.
+ */
+export function emitCss(doc, options = {}) {
+    const resolved = optionsOf(doc, options);
+    const { light, dark } = plansOf(doc, options);
+    const parts = [header(doc), '', block(':root', light), '', block(resolved.darkSelector, dark)];
+    if (resolved.prefersColorScheme) {
+        // Biblioteka nie czyta `prefers-color-scheme` — aplikacja albo ustawia `data-theme` sama,
+        // albo bierze ten blok. Negacja na `light` zostawia jawny wybór użytkownika ważniejszym
+        // od ustawienia systemu.
+        const inner = block(':root:not([data-theme="light"])', dark, '    ')
+            .split('\n')
+            .map((line) => `  ${line}`)
+            .join('\n');
+        parts.push('', '@media (prefers-color-scheme: dark) {', inner, '}');
+    }
+    return `${parts.join('\n')}\n`;
+}
+/** Ten sam motyw jako mixiny SCSS — dla konsumentów kompilujących style ze źródeł. */
+export function emitScss(doc, options = {}) {
+    const resolved = optionsOf(doc, options);
+    const plans = plansOf(doc, options);
+    const declare = (map) => sorted(map)
+        .map(([name, value]) => `    ${name}: ${value};`)
+        .join('\n');
+    return `// Koncept UI theme${doc.meta?.name ? ` "${doc.meta.name}"` : ''} — ui.konce.pt/theme
+// Użycie: @use './kpt-theme'; @include kpt-theme.light; @include kpt-theme.dark;
+
+@mixin light {
+  :root {
+${declare(plans.light)}
+  }
+}
+
+@mixin dark {
+  ${resolved.darkSelector} {
+${declare(plans.dark)}
+  }
+}
+`;
+}
+/**
+ * Motyw jako moduł TypeScriptu, razem z funkcją nakładającą go w runtime.
+ *
+ * Plik jest samowystarczalny — zero importów — bo trafia do repozytorium konsumenta, gdzie
+ * `@konce-pt/theme` nie musi być zainstalowany. To jest droga dla aplikacji, w których motyw
+ * wybiera użytkownik końcowy, a nie build.
+ */
+export function emitTs(doc, options = {}) {
+    const plans = plansOf(doc, options);
+    const entries = (mode) => sorted(plans[mode])
+        .map(([name, value]) => `    ${JSON.stringify(name)}: ${JSON.stringify(value)},`)
+        .join('\n');
+    return `// Koncept UI theme${doc.meta?.name ? ` "${doc.meta.name}"` : ''} — ui.konce.pt/theme
+// Wygenerowane. Zero zależności — plik jest samowystarczalny.
+
+export const KPT_THEME = {
+  light: {
+${entries('light')}
+  },
+  dark: {
+${entries('dark')}
+  },
+} as const;
+
+export type KptThemeMode = keyof typeof KPT_THEME;
+
+/** Nakłada motyw na element (domyślnie <html>) przez style inline. Zwraca funkcję cofającą. */
+export function applyKptTheme(mode: KptThemeMode, element: HTMLElement = document.documentElement): () => void {
+  const applied = Object.entries(KPT_THEME[mode]);
+  for (const [name, value] of applied) element.style.setProperty(name, value);
+  return () => {
+    for (const [name] of applied) element.style.removeProperty(name);
+  };
+}
+`;
+}
+const COLOR = /^(oklch|rgb|hsl|color|#)/i;
+const DIMENSION = /^-?(?:\d*\.\d+|\d+)(px|rem|em|%)$/;
+/** Typ DTCG zgadnięty z kształtu wartości — źródła biblioteki nie niosą typów w tej postaci. */
+const dtcgType = (value) => {
+    if (COLOR.test(value.trim()))
+        return 'color';
+    if (DIMENSION.test(value.trim()))
+        return 'dimension';
+    if (/^-?(?:\d*\.\d+|\d+)$/.test(value.trim()))
+        return 'number';
+    if (value.includes('px ') || value.includes('rem '))
+        return 'shadow';
+    return 'other';
+};
+/**
+ * Eksport w formacie W3C Design Tokens. Tryby jasny i ciemny idą jako dwie grupy najwyższego
+ * poziomu, bo **DTCG nie standaryzuje trybów** — każdy eksporter koduje je inaczej i nie ma
+ * zapisu, który byłby tu „poprawny". Dwie grupy są przynajmniej jednoznaczne i czytelne dla
+ * człowieka, a importer po drugiej stronie i tak wymaga wskazania, co jest czym.
+ *
+ * To jest eksport do narzędzi projektowych, nie synchronizacja.
+ */
+export function emitDtcg(doc, options = {}) {
+    const plans = plansOf(doc, options);
+    const group = (mode) => {
+        const out = {};
+        for (const [name, value] of sorted(plans[mode])) {
+            // Prefiks zdejmujemy także tokenom własnym: w DTCG nazwa jest ścieżką w drzewie, a nie
+            // custom property, więc `--` po drugiej stronie jest śmieciem, nie informacją.
+            out[name.replace(/^--(kpt-)?/, '')] = {
+                $value: value,
+                $type: dtcgType(value),
+                ...(isKnownToken(name) ? {} : { $description: 'Token własny motywu (spoza biblioteki).' }),
+            };
+        }
+        return out;
+    };
+    return `${JSON.stringify({
+        $description: `Koncept UI theme${doc.meta?.name ? ` "${doc.meta.name}"` : ''} — export, not sync.`,
+        light: group('light'),
+        dark: group('dark'),
+    }, null, 2)}\n`;
+}
+/** Ile tokenów zmienia motyw względem stocku — do podsumowania w interfejsie. */
+export function themeSize(doc) {
+    const light = themeDiff(doc, 'light');
+    const dark = themeDiff(doc, 'dark');
+    const semantic = new Set([...Object.keys(light), ...Object.keys(dark)].filter((n) => SEMANTIC.has(n)));
+    return { light: Object.keys(light).length, dark: Object.keys(dark).length, semantic: semantic.size };
+}
+/** Wartości stockowe — wystawione, żeby edytor mógł pokazać „wróć do domyślnej". */
+export const stockValue = (name, mode) => stockTheme()[mode][name];
+export const rawValue = (name, mode) => KPT_RAW[name]?.[mode];

package/dist/generated/tokens.d.ts

@@ -0,0 +1,24 @@
+/** Stopnie pełnej skali, tak jak rozkłada je rampa neutralna biblioteki. */
+export declare const KPT_RAMP_STEPS: readonly number[];
+/** Jasność OKLCH na każdym stopniu — krzywa wzięta z rampy neutralnej. */
+export declare const KPT_RAMP_LIGHTNESS: Readonly<Record<number, number>>;
+/** Kształt nasycenia na każdym stopniu, 0–1: uśredniony z czterech ramp akcentowych. */
+export declare const KPT_RAMP_CHROMA: Readonly<Record<number, number>>;
+/** Największe nasycenie w rampach akcentowych — skala, do której odnosi się krzywa. */
+export declare const KPT_RAMP_PEAK_CHROMA = 0.18325;
+/** Stopnie rodziny akcentowej per motyw, odczytane z danger/success/warning/info. */
+export declare const KPT_ACCENT_PATTERN: Readonly<Record<string, {
+    light: number;
+    dark: number;
+}>>;
+/** Nazwy tokenów warstwy semantycznej (te i tylko te zmienia motyw). */
+export declare const KPT_SEMANTIC_TOKENS: readonly string[];
+/**
+ * Wartości stockowe wszystkich tokenów w obu motywach, w postaci SUROWEJ: `{--kpt-nazwa}` to
+ * referencja do innego tokenu. Rozwiązuje je `resolveTheme` — dzięki temu nadpisanie prymitywu
+ * przestawia wszystko, co się na niego powołuje, tak samo jak zrobiłaby to kaskada CSS.
+ */
+export declare const KPT_RAW: Readonly<Record<string, {
+    light: string;
+    dark: string;
+}>>;