name	description
datastar	Apply datastar best practices, idioms, and conventions from https://data-star.dev/reference/attributes. Use when writing, reviewing, or refactoring html/frontend code to ensure idiomatic, clean, and efficient implementations.

Datastar (data-star.dev) — Claude/OpenCode SKILL

Tikslas: šiame faile aprašyta, kaip teisingai ir produktyviai naudoti Datastar kuriant backend-driven (hypermedia-first) UI. Tekstas skirtas LLM „skill“ formato naudojimui: aiškios taisyklės, receptai, šablonai, „gotchas“, ir mini pavyzdžiai.

Kas yra Datastar (mentalus modelis)

Datastar yra lengvas hypermedia framework’as, kuris sujungia:

Frontend reaktivumą per data-* atributus (panašu į Alpine idėją),
Backend-driven DOM patch’inimą (panašu į htmx idėją),
Vieningą būsenos modelį per „signals“ ($signalai), kurie keliauja tarp FE ir BE.

Datastar du pagrindiniai „superpower“:

Backend’as gali patch’inti DOM (HTML fragmentais) ir patch’inti signalus.
Frontend’as gali deklaratyviai aprašyti elgseną per data-* atributus ir siųsti užklausas per saugias @action() funkcijas.

Šaltinis: Getting Started (apie hypermedia-first, data-* ir patch’inimą). (data-star.dev)

Frontend includes

Naudok šitą FE JavaScript include (CDN):

<script type="module" src="https://cdn.jsdelivr.net/gh/starfederation/datastar@1.0.0-RC.7/bundles/datastar.js"></script>

Pastaba: oficiali dokumentacija Getting Started rodo analogišką include per jsdelivr ir „bundles/datastar.js“. (data-star.dev)

Golang backend SDK

Naudok Golang SDK:

http://github.com/starfederation/datastar-go/datastar

Šiame SKILL faile pateikiami BE pavyzdžiai yra konceptiniai šablonai: realūs API pavadinimai/func’ijos priklauso nuo datastar-go versijos ir tavo pasirinkto HTTP framework’o.

Pagrindiniai terminai

Signalas: reakt. kintamasis, kurio pavadinimas naudojamas su $ (pvz. $search, $count, $user.name). Signalai gali būti objektai (nested) ir turi tipą (number/string/array/obj).
Expression: string’as data-* atribute, kuris vertinamas Datastar „sandboxe“. Panašu į JS, bet su signalų substitucija.
Action: saugi helper funkcija su @ prefiksu (@get(), @post() ir pan.). @ yra saugumo ribotuvas prieš „bet kokį JS“. (data-star.dev)
Patch Elements: backend’o atsakymas su content-type: text/html, kuriame top-level elementai (su id) yra morphed į egzistuojantį DOM. (data-star.dev)

Datastar expressions (kaip galvoti apie išraiškas)

Taisyklės

data-* atributų reikšmės yra išraiškos.
$foo reiškia signalo foo reikšmę.
el kintamasis visada pasiekiamas ir rodo elementą, ant kurio yra atributas. (data-star.dev)
JS operatoriai veikia (?:, &&, ||, aritmetika ir t.t.). (data-star.dev)
Gali rašyti kelis statement’us su ;.
Jei išraiška yra async — Datastar jos nelauks (asynchrony geriau daryti per actions arba custom events).

Mini pavyzdžiai

<div data-signals:foo="1">
  <div data-text="$foo"></div>
</div>

<div data-text="el.offsetHeight"></div>

<button data-on:click="$ready && @post('/launch')">Launch</button>

Šaltinis: Expressions guide. (data-star.dev)

Atributų apdorojimo tvarka ir „casing“

Evaluation order

Datastar eina per DOM depth-first ir atributus taiko tokia tvarka, kokia jie surašyti elemente.
Tai svarbu, kai vienas atributas sukuria signalą, o kitas jį tuoj pat naudoja (pvz. data-indicator prieš data-init). (data-star.dev)

Casing (camel/kebab/snake)

HTML data-* atributai yra case-insensitive.
Signalų apibrėžimo atributuose (data-signals:*, data-bind:*, data-computed:*) sufiksai normalizuojami į camelCase.
Kituose atributuose (pvz. data-class:..., data-on:...) sufiksai pagal nutylėjimą elgiasi kaip kebab-case.
__case modifikatorius leidžia perjungti casing’ą.

Šaltinis: Attributes reference (Attribute Casing). (data-star.dev)

Atributų katalogas (FOSS)

Žemiau — dažniausiai naudojami atributai. Visi pavyzdžiai yra minimalūs; realybėje dažnai kombinuosi kelis atributus ant to paties elemento.

`data-attr`

Nustato bet kokį HTML atributą pagal išraišką ir palaiko sinchronizaciją.

<div data-attr:aria-label="$foo"></div>
<div data-attr="{'aria-label': $foo, disabled: $bar}"></div>

Šaltinis: Attributes reference. (data-star.dev)

`data-bind`

Sukuria signalą (jei jo nėra) ir padaro two-way binding su elemento value.

Veikia su input, select, textarea, web components.
Klausosi change ir input.
Signalą gali nurodyti rakte arba value.

<input data-bind:search />
<input data-bind="search" />

<!-- casing: abu sukuria $fooBar -->
<input data-bind:foo-bar />
<input data-bind="fooBar" />

Tipai: jei signalą iš anksto apibrėži su tipu, binding konvertuoja į tą tipą (pvz. number). (data-star.dev)

Checkbox masyvai: predefinink [], kad keli checkbox’ai pildytų masyvą. (data-star.dev)

File input: type=file automatiškai encodina turinį į base64 ir sukuria signalą {name, contents, mime}[]. (data-star.dev)

`data-class`

Prideda/nuima CSS class pagal boolean išraišką. Taip pat palaiko objektinę formą.

<div data-class:font-bold="$foo == 'strong'"></div>
<div data-class="{success: $foo != '', 'font-bold': $foo == 'strong'}"></div>

__case leidžia pakeisti class name casing’ą, kai class pavadinimą generuoji per sufiksą. (data-star.dev)

`data-computed`

Sukuria read-only signalą, kurio reikšmė automatiškai perskaičiuojama, kai keičiasi priklausomi signalai.

<div data-computed:sum="$a + $b"></div>
<div data-text="$sum"></div>

<div data-computed="{sum: () => $a + $b}"></div>

Svarbi taisyklė: computed neturi būti naudojamas side-effect’ams (keisti kitus signalus, kviesti actions). Tam yra data-effect. (data-star.dev)

`data-effect`

Vykdo išraišką page-load metu ir kiekvieną kartą, kai pasikeičia signalai išraiškoje. Skirta side-effect’ams.

<div data-effect="$fullName = `${$first} ${$last}`"></div>

Šaltinis: Attributes reference. (data-star.dev)

`data-ignore` / `data-ignore-morph`

data-ignore: Datastar visai neapdoroja elemento ir jo vaikų.
data-ignore-morph: PatchElements morpher’is praleidžia elementą ir vaikus.

Naudinga, kai:

yra konfliktas su kita biblioteka,
yra turinys, kurio negali/nenori „escape’inti“.

Šaltinis: Attributes reference. (data-star.dev)

`data-indicator`

Sukuria signalą ir nustato jį į true kol vyksta fetch request’as, o pabaigoje į false.

<button
  data-on:click="@get('/endpoint')"
  data-indicator:fetching
  data-attr:disabled="$fetching"
>Go</button>

<div data-show="$fetching" style="display:none">Loading...</div>

Svarbu: jei naudoji su data-init, indikatorius turi būti anksčiau už init (evaluation order). (data-star.dev)

`data-init`

Vykdo išraišką, kai atributas inicializuojamas (page load, patch’inimas į DOM, atributo pakeitimas).

<div data-init="$count = 1"></div>
<div data-init__delay.500ms="$count = 1"></div>

Šaltinis: Attributes reference. (data-star.dev)

`data-json-signals`

Išveda signalus kaip JSON (debug/troubleshooting). Gali filtruoti include/exclude regex’ais ir naudoti __terse.

<pre data-json-signals></pre>
<pre data-json-signals="{include: /user/}"></pre>
<pre data-json-signals__terse="{include: /counter/}"></pre>

Šaltinis: Attributes reference. (data-star.dev)

`data-on`

Prikabina event listener’į ir vykdo išraišką, kai event’as įvyksta.

<button data-on:click="$search = ''">Reset</button>
<div data-on:my-event="$foo = evt.detail"></div>

evt visada pasiekiamas ir yra event object. data-on:submit automatiškai prevent’ina form submit pagal nutylėjimą. (data-star.dev)

Modifikatoriai (dažniausi):

__once, __passive, __capture
__delay.500ms, __debounce.200ms, __throttle.1s
__window (klausyti globaliai), __outside (outside click)
__prevent, __stop
__case.camel|kebab|snake|pascal
__viewtransition

Šaltinis: Attributes reference (data-on modifiers). (data-star.dev)

`data-on-intersect`

Vykdo išraišką, kai elementas intersect’ina su viewport’u (IntersectionObserver).

Dažni modifikatoriai: __once, __exit, __half, __full, __threshold.25, taip pat __delay/__debounce/__throttle ir __viewtransition.

Šaltinis: Attributes reference (data-on-intersect). (data-star.dev)

`data-on-interval`

Vykdo išraišką periodiškai.

<div data-on-interval="$count++"></div>
<div data-on-interval__duration.500ms="$count++"></div>
<div data-on-interval__duration.1s.leading="$count++"></div>

Šaltinis: Attributes reference. (data-star.dev)

`data-on-signal-patch` ir `data-on-signal-patch-filter`

data-on-signal-patch: kviečiamas kiekvieną kartą, kai patch’inami signalai.
patch kintamasis pasiekiamas išraiškoje.
data-on-signal-patch-filter: filtruoja, kuriuos signalus sekti (include/exclude regex).

<div data-on-signal-patch="console.log(patch)"></div>
<div data-on-signal-patch-filter="{include: /^counter$/}"></div>

Šaltinis: Attributes reference. (data-star.dev)

`data-preserve-attr`

Sako morpher’iui išsaugoti nurodytų atributų reikšmes per DOM morph (pvz., open, class).

<details open data-preserve-attr="open">
  <summary>Title</summary>
  Content
</details>

<details open class="foo" data-preserve-attr="open class">...</details>

Šaltinis: Attributes reference. (data-star.dev)

`data-ref`

Sukuria signalą, kuris yra nuoroda į elementą (t.y. į DOM node).

<div data-ref:foo></div>
$foo is a reference to a <span data-text="$foo.tagName"></span> element

Šaltinis: Attributes reference. (data-star.dev)

`data-show`

Parodo/paslepia elementą pagal boolean išraišką.

<div data-show="$isOpen" style="display:none"></div>

Patarimas: style="display:none" padeda išvengti „flicker“ prieš Datastar inicializaciją. (data-star.dev)

`data-signals`

Patch’ina (prideda/atnaujina/pašalina) signalus. Vėliau DOM’e esantys apibrėžimai override’ina ankstesnius.

<div data-signals:foo="1"></div>
<div data-signals:foo.bar="1"></div>
<div data-signals="{foo: {bar: 1, baz: 2}}"></div>

<!-- pašalinimas -->
<div data-signals="{foo: null}"></div>

Svarbu:

Signalai, prasidedantys _, pagal nutylėjimą nesiunčiami į backend’ą.
Signalų pavadinimuose negali būti __ (dvigubo underscore), nes tai modifikatorių delimiter’is.
__ifmissing leidžia nustatyti default’us neperrašant esamų reikšmių.

Šaltinis: Attributes reference. (data-star.dev)

`data-style`

Valdo inline CSS style reikšmes reaktiškai (palaiko vieną property arba objektą).

<div data-style:display="$hiding && 'none'"></div>
<div data-style:background-color="$red ? 'red' : 'blue'"></div>

<div data-style="{
  display: $hiding ? 'none' : 'flex',
  'background-color': $red ? 'red' : 'green'
}"></div>

Kai išraiška tampa „falsy“ ('', null, undefined, false), Datastar atstato pradinę inline style reikšmę (jei buvo) arba pašalina property. (data-star.dev)

`data-text`

Binds element textContent į išraišką.

<div data-text="$foo"></div>

Šaltinis: Attributes reference. (data-star.dev)

Pro atributai (komercinė licencija)

Dokumentacija aiškiai pažymi, kad Pro atributai yra papildoma funkcija su komercine licencija. (data-star.dev)

`data-animate`

Animuoja elementų atributus laike (reaktyviai, kai keičiasi signalai). (data-star.dev)

`data-custom-validity`

Leidžia nustatyti custom validity message pagal išraišką (tuščia = valid). (data-star.dev)

`data-on-raf`

Vykdo išraišką ant kiekvieno requestAnimationFrame. Turi __throttle.*. (data-star.dev)

`data-on-resize`

Vykdo išraišką, kai keičiasi elemento dimensijos. Turi __debounce ir __throttle. (data-star.dev)

`data-persist`

Persist’ina signalus į LocalStorage, galima filtruoti, galima naudoti custom key (data-persist:mykey) ir __session į SessionStorage. (data-star.dev)

`data-query-string`

Sync’ina query string params ↔ signalai (page load + on change). __filter ir __history. (data-star.dev)

`data-replace-url`

Keičia browser URL be reload (išraiška). (data-star.dev)

`data-scroll-into-view`

Scroll’ina elementą į view. Turi modifikatorių rinkinį scroll elgsenai ir fokusui (__smooth, __instant, __vstart, __focus, …). (data-star.dev)

`data-rocket`

Sukuria Rocket web component (detalės atskirame Rocket reference). (data-star.dev)

`data-view-transition`

Nustato view-transition-name ir padeda valdyti View Transition API integraciją. (data-star.dev)

Actions (pagrindai ir saugumas)

Actions sintaksė: @actionName(args...).
@ prefiksas reiškia: „saugus, leistinas vykdymas“ — Datastar riboja, kad išraiškose nebūtų vykdomas bet kas.

Šaltinis: Actions reference (apie @ kaip security feature). (data-star.dev)

Dažniausiai naudojama: backend request’ai

Dokumentacija Getting Started rodo, kad @get('/endpoint') siunčia fetch request’ą, o jei atsakymas text/html, elementai morphed į DOM pagal id. (data-star.dev)

Pavyzdys:

<button data-on:click="@get('/endpoint')">Load</button>
<div id="target"></div>

Backend (konceptualiai) grąžina:

<div id="target">Naujas turinys</div>

Pattern receptai (copy/paste mental models)

1) Active Search (live paieška su debounce)

Oficialus pavyzdys:

<input
  type="text"
  placeholder="Search..."
  data-bind:search
  data-on:input__debounce.200ms="@get('/examples/active_search/search')"
/>

Kas vyksta:

data-bind:search sukuria / atnaujina $search.
data-on:input__debounce.200ms klausosi input event’o ir debouncina.
@get(...) išsiunčia GET; signalai (įskaitant $search) keliauja su request’u.

Šaltinis: Active Search example. (data-star.dev)

Praktinis patobulinimas (UX):

data-indicator:loading + data-show spinner’is
server-side limit’ai (pvz. min 2 simboliai)

<div data-signals="{search: ''}">
  <input
    data-bind:search
    data-on:input__debounce.200ms="$search.length >= 2 && @get('/search')"
    placeholder="Search..."
  />
  <div data-show="$loading" style="display:none">Loading…</div>
</div>

Pastaba: šiame patobulinime loading signalą sukurtų data-indicator:loading ant to paties elemento, kuris triggerina request’ą.

2) Keydown binding į konkrečius klavišus (globaliai)

Oficialus how-to parodo data-on:keydown__window ir evt naudojimą. (data-star.dev)

Enter:

<div data-on:keydown__window="evt.key === 'Enter' && alert('Key pressed')"></div>

Ctrl + L:

<div data-on:keydown__window="evt.ctrlKey && evt.key === 'l' && alert('Key pressed')"></div>

Kombinuotas:

<div data-on:keydown__window="(evt.key === 'Enter' || (evt.ctrlKey && evt.key === 'l')) && alert('Key pressed')"></div>

Prevent default (pvz. form submit ant Enter):

<div data-on:keydown__window="evt.key === 'Enter' && (evt.preventDefault(), alert('Key pressed'))"></div>

„Gotchas“ ir best practices

1) Atributų tvarka yra realus dalykas

Kai vienas atributas turi sukurti signalą, o kitas jį naudoja, laikykis tvarkos.

Pavyzdys: data-indicator turi būti prieš data-init, jei data-init triggerina request’ą. (data-star.dev)

2) `data-computed` nėra skirtas side-effect’ams

Computed turėtų būti grynas (pure) ir be šalutinių efektų. Jei nori reaguoti į signalų pokytį — naudok data-effect. (data-star.dev)

3) „Daryk mažiau JS, daugiau HTML“ — bet neperlenk

Expressions guide perspėja: jei bandai sugrūsti per daug logikos į išraiškas, greičiausiai perkomplikuoji. Geriau:

iškelti į external script arba web component,
arba naudoti custom events (props down / events up).

Šaltinis: Expressions guide (Using JavaScript). (data-star.dev)

4) Debug’ui naudok `data-json-signals`

Kai „nesupranti, kas vyksta“, data-json-signals + filter’is yra greičiausias reality-check. (data-star.dev)

Backend integracijos gairės (Golang)

Ši dalis yra „praktinis stuburas“: kaip projektuoti endpoint’us, kad Datastar FE elgtųsi gražiai.

1) GET/POST endpoint’ai, kurie grąžina HTML fragmentus

FE iškviečia @get('/x') ar @post('/y').
Backend grąžina Content-Type: text/html ir elementus su stabiliais id, kuriuos Datastar morp’intų.
Vienu atsakymu gali patch’inti kelis elementus (kelis top-level node’us).

Šaltinis: Getting Started apie patch elements per text/html. (data-star.dev)

2) Signalų siuntimas į backend’ą

Frontend’e signalai yra $....
Datastar siunčia signalus su request’ais (pvz. Active Search pavyzdyje $search keliauja su GET). (data-star.dev)

Konkreti signalų serializacija (query/body/header) priklauso nuo SDK ir Datastar versijos; datastar-go tipinėje integracijoje paprastai yra helper’iai signalams nuskaityti ir atsakymui generuoti.

3) Ilgesnės operacijos

UX gerinimui naudok data-indicator + data-show.
Jei darbas ilgas, tipinis hypermedia kelias: SSE stream’as arba periodinis poll’inimas (data-on-interval su @get).

data-on-interval yra built-in ir paprastas. (data-star.dev)

Minimalus „starter“ šablonas (vienam puslapiui)

<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width,initial-scale=1" />
    <script type="module" src="https://cdn.jsdelivr.net/gh/starfederation/datastar@1.0.0-RC.7/bundles/datastar.js"></script>
  </head>
  <body>
    <div data-signals="{search: ''}">
      <input
        data-bind:search
        data-on:input__debounce.200ms="@get('/search')"
        placeholder="Search..."
      />
      <div id="results"></div>
    </div>
  </body>
</html>

Serveris grąžina:

<div id="results">
  <!-- naujas sąrašas -->
</div>

Pagrindinės idėjos remiasi Getting Started + Active Search pavyzdžiu. (data-star.dev)

Greita atmintinė (cheat sheet)

Signalas: $name, $user.name
Sukurti signalą: data-signals:foo="1"
Bind input: data-bind:search
Reaguoti į event’ą: data-on:click="..."
Debounce: __debounce.200ms
Global keydown: data-on:keydown__window="..."
Fetch indikatorius: data-indicator:loading + data-show="$loading"
DOM patch: backend grąžina text/html su elementais, kurie turi id

Šaltiniai (naudoti šio SKILL paruošimui)

Attributes reference: https://data-star.dev/reference/attributes (data-star.dev)
Active Search example: https://data-star.dev/examples/active_search (data-star.dev)
Keydown how-to: https://data-star.dev/how_tos/bind_keydown_events_to_specific_keys (data-star.dev)
Getting Started: https://data-star.dev/guide/getting_started (data-star.dev)
Expressions guide: https://data-star.dev/guide/datastar_expressions (data-star.dev)
Actions reference: https://data-star.dev/reference/actions (data-star.dev)

blinkinglight/datastar_SKILL.md

Datastar (data-star.dev) — Claude/OpenCode SKILL

Kas yra Datastar (mentalus modelis)

Frontend includes

Golang backend SDK

Pagrindiniai terminai

Datastar expressions (kaip galvoti apie išraiškas)

Taisyklės

Mini pavyzdžiai

Atributų apdorojimo tvarka ir „casing“

Evaluation order

Casing (camel/kebab/snake)

Atributų katalogas (FOSS)

data-attr

data-bind

data-class

data-computed

data-effect

data-ignore / data-ignore-morph

data-indicator

data-init

data-json-signals

data-on

data-on-intersect

data-on-interval

data-on-signal-patch ir data-on-signal-patch-filter

data-preserve-attr

data-ref

data-show

data-signals

data-style

data-text

Pro atributai (komercinė licencija)

data-animate

data-custom-validity

data-on-raf

data-on-resize

data-persist

data-query-string

data-replace-url

data-scroll-into-view

data-rocket

data-view-transition

Actions (pagrindai ir saugumas)

Dažniausiai naudojama: backend request’ai

Pattern receptai (copy/paste mental models)

1) Active Search (live paieška su debounce)

2) Keydown binding į konkrečius klavišus (globaliai)

„Gotchas“ ir best practices

1) Atributų tvarka yra realus dalykas

2) data-computed nėra skirtas side-effect’ams

3) „Daryk mažiau JS, daugiau HTML“ — bet neperlenk

4) Debug’ui naudok data-json-signals

Backend integracijos gairės (Golang)

1) GET/POST endpoint’ai, kurie grąžina HTML fragmentus

2) Signalų siuntimas į backend’ą

3) Ilgesnės operacijos

Minimalus „starter“ šablonas (vienam puslapiui)

Greita atmintinė (cheat sheet)

Šaltiniai (naudoti šio SKILL paruošimui)

`data-attr`

`data-bind`

`data-class`

`data-computed`

`data-effect`

`data-ignore` / `data-ignore-morph`

`data-indicator`

`data-init`

`data-json-signals`

`data-on`

`data-on-intersect`

`data-on-interval`

`data-on-signal-patch` ir `data-on-signal-patch-filter`

`data-preserve-attr`

`data-ref`

`data-show`

`data-signals`

`data-style`

`data-text`

`data-animate`

`data-custom-validity`

`data-on-raf`

`data-on-resize`

`data-persist`

`data-query-string`

`data-replace-url`

`data-scroll-into-view`

`data-rocket`

`data-view-transition`

2) `data-computed` nėra skirtas side-effect’ams

4) Debug’ui naudok `data-json-signals`