← Wszystkie wpisy

API i helpers

window.JZ: helpers do sterowania przyciskami, sliderami i Output Console z kodu

15 maja 2026 · autor JustZix Team

Zapomnij na chwilę, że JustZix wstrzykuje CSS i JS na każdej stronie. Skup się na tym, że każda akcja — button, slider, select, toggle3, input, textarea — to żywy element DOM, którym możesz manipulować z innego kodu. Wystarczą dwa osobne namespacy w MAIN world: window.JZ (action helpers) i window.JUSTZIX (logger). Każdy ma własny lifecycle, własne cele, i celowo nie miesza się z drugim.

Dlaczego dwa namespacy, a nie jeden

Logger (write-only, dispatch do Output Console) i addressability DOM (read/manipulate elementów które już są w DOM) to dwie różne semantyki. Pakowanie ich razem mieszałoby concerns. User czytający kod widzi JUSTZIX.log(...) i wie: "to logger". Widzi document.querySelector('[data-jz-action-id="x"]') i wie: "to DOM query". Plus — natywne DOM API + data-* atrybuty zawsze wygrywają z proprietary wrapper'em (działa z DevTools inspect, z third-party libraries, z copy-paste z internetu).

Idempotentnie — instalacja jest gated wersją (_jzVersion dla JZ, hook flag dla JUSTZIX), więc upgrade'y wtyczki nie nadpiszą Ci namespace'ów w trakcie sesji.

Pełna powierzchnia API

// ============================================================
// window.JZ — Action helpers
// Operuje na elementach z data-jz-action-id w DOM.
// Może być zajęte przez page scripts → fallback: natywny DOM query.
// ============================================================
JZ.action(labelOrId)     // Element po labelu LUB ID. Case-insensitive po labelu.
JZ.actionById(id)        // Element po data-jz-action-id. Bez fallbacka po labelu.
JZ.actions()             // Tablica wszystkich elementów akcji w DOM.
JZ.labels()              // Tablica labeli (oryginalny case).
JZ.click(labelOrId)      // Programatic click. Dla <select> wybiera pierwszą opcję.
                          // Zwraca true/false.
JZ.value(labelOrId)      // Aktualna wartość akcji (string lub null).
JZ.setValue(labelOrId, value)  // Programatic setter + dispatch input + change event.
JZ.bars()                // Tablica wszystkich .jz-actions-bar w DOM.
JZ.barById(id)           // Bar po data-jz-bar-id.
JZ.floatingBtn()         // Element pływającego przycisku JustZix (jeśli włączony).

// ============================================================
// window.JUSTZIX — Logger (od v2.13.73, primary alias od v2.13.76)
// Dispatch do Output Console (kind='jz'); NIE leci do natywnej console.*
// Brand name = znikoma szansa collision. Działa wszędzie.
// ============================================================
JUSTZIX.log(...args)
JUSTZIX.warn(...args)
JUSTZIX.error(...args)
JUSTZIX.info(...args)
JUSTZIX.debug(...args)

// Aliasy na to samo API:
window.__JUSTZIX__       // zawsze ustawiony (backwards-compat z v2.13.72-75)
window.JZ                // tylko jeśli wolne — krótszy skrót

// Fallback gdy window.JZ jest zajęte przez stronę (np. Google Ads):
// → brak equivalentu JUSTZIX.click(); używaj natywnego DOM.
document.querySelector('[data-jz-action-id="..."]').click();

Use case 1 — przycisk klika inny przycisk

Masz akcję "Login → Dashboard → Stats". Trzy oddzielne przyciski w action barze. Możesz dodać czwarty "🚀 Quick" który robi wszystko po kolei:

// Akcja BUTTON "Quick" — pole "Code":
JZ.click('Login');
await new Promise(r => setTimeout(r, 800));
JZ.click('Dashboard');
await new Promise(r => setTimeout(r, 500));
JZ.click('Stats');
JUSTZIX.log('Quick flow done in 3 clicks → 1');

Korzyść: skrypt nie wie nic o stronie, tylko o własnych akcjach JustZix. Jak zmienisz selectory w "Login" / "Dashboard" — "Quick" wciąż działa, bo woła je po labelu.

Use case 2 — slider steruje CSS variable

Akcja SLIDER "Jasność" (zakres 50-150, default 100). W jej polu "Code" wpisujesz:

// Slider odpala ten kod przy każdej zmianie.
// `value` to extraVar wstrzykiwany przez wtyczkę (od v2.12.2).
document.documentElement.style.setProperty('--brightness', value + '%');

Teraz w innej akcji (BUTTON "Reset") możesz programmatic ustawić wartość slidera:

JZ.setValue('Jasność', 100);  // Slider skacze na 100, CSS variable odpalany, jasność resetowana.
JUSTZIX.log('Brightness reset to 100%');

To samo działa dla TOGGLE3 (3-stanowych przełączników typu "Dev / Staging / Prod"): JZ.setValue('Środowisko', 'staging') ustawia konkretny stan i odpala jego kod.

Use case 3 — Output Console jako "scratch pad"

Output Console (od v2.13.66) to okno typu pane, które łapie wszystko z console.log strony. To bywa hałaśliwe — strony jak Gmail piszą do konsoli setki linii na sekundę. Filtrowanie po stringu pomaga, ale lepszy trik: pisz tylko swoje logi przez JUSTZIX.log, potem przełącz panel w tryb [J] (Just JustZix).

// W akcji "Verify cart": loguj tylko TWOJE komunikaty, bez szumu strony.
const items = document.querySelectorAll('.cart-item');
JUSTZIX.log(`Cart has ${items.length} items`);
items.forEach((it, i) => {
  const price = parseFloat(it.querySelector('.price')?.textContent || 0);
  JUSTZIX.log(`  [${i}] ${it.dataset.sku} — ${price} PLN`);
});
const total = [...items].reduce((s, it) => s + parseFloat(it.querySelector('.price')?.textContent || 0), 0);
JUSTZIX.log(`Total: ${total} PLN`);

Panel Output Console w trybie [J] pokazuje TYLKO te 3 wiersze — całkowicie czyste, idealne dla QA toolbara lub kontekstu klienta.

Co gdy strona ma własne window.JZ?

Logger zawsze działa — JUSTZIX.log() ma brand name (znikoma szansa collision) i jest primary. Plus window.__JUSTZIX__ jest ustawiony zawsze jako fallback alias. Konflikt z window.JZ dotyczy tylko action helpers — i nawet wtedy masz natywne wyjście.

Niektóre strony mają własny window.JZ (np. Google Ads). JustZix wykrywa to: jeśli window.JZ już istnieje przy instalacji loggera, wtyczka nie nadpisuje cudzego API i zapisuje informację w welcome message Output Console. Krótki skrót JZ jest wtedy zarezerwowany dla strony — Ty używaj JUSTZIX dla loggera i natywnego DOM dla akcji:

// Logger: zawsze JUSTZIX (działa nawet gdy JZ zajęte przez stronę)
JUSTZIX.log('Cart processed');

// Action click: gdy window.JZ jest zajęte → natywny DOM zamiast JZ.click()
document.querySelector('[data-jz-action-id="actionId"]').click();
// Lub po data-jz-key (label upper-case):
document.querySelector('.jz-actions-bar [data-jz-key="LOGIN"]').click();

To celowy design: data-jz-action-* + querySelector to natywny pattern, działa z DevTools inspect, z third-party libraries, z copy-paste z internetu. JZ.click() to sugar — opcjonalna warstwa indirection którą można pominąć kiedy nie jest dostępna.

Pułapki

• JZ.click() dla INPUT/TEXTAREA tylko klika, nie zmienia value. Żeby ustawić tekst: JZ.setValue('Search', 'foo'). Reszta typów (button, select, toggle3, slider) robi sensowny default dla click.
• JZ.value()/setValue() mają najpełniejszą obsługę od v2.13.33. Starsze wersje brakowały slider value w datasecie — jeśli widzisz null dla slidera, sprawdź wersję wtyczki.
• Lookup po labelu jest case-insensitive, ale po ID — case-sensitive. Polecane: trzymaj się labeli (Twoje), nie ID (auto-generated).
• JUSTZIX.log NIE leci do DevTools console. To celowe — chcemy oddzielnego kanału dla skryptów JustZix. Jeśli akurat chcesz przez DevTools — używaj normalnego console.log.
• JS Console wpisuje TYLKO do DevTools-style capture, nie do JUSTZIX.log automatycznie. Wpis "console.log('hi')" w JS Console działa jak zawsze; "JUSTZIX.log('hi')" w JS Console NIE pojawi się w Output Console o ile nie masz Output Console panela aktywnego w trybie [J] lub [C+J].
• Brak JUSTZIX.click() i podobnych. Logger i action helpers to osobne namespacy w design'ie. Jak strona zabierze window.JZ, akcje wykonujesz przez natywny DOM (querySelector + data-jz-action-*) — to nie bug, to pattern.

Co dalej

To zamyka mini-serię o oknach na froncie JustZix:

• CSS pane — live edytor CSS w karcie
• JS Console — REPL z historią ↑↓
• JS pane — Run-on-demand
• window.JZ helpers (ten post) — programmatic API

Wszystko razem to mini-IDE wewnątrz każdej karty przeglądarki, z mini-API do sterowania własnymi przyciskami. Zainstaluj JustZix i sprawdź sam — kompletnie za darmo, bez konta, bez serwera.