Reference › Project
clarusjs 0.9.0
All releases · [email protected] on npm
Minor Changes
browserfromclarusjs/runtime: true in the browser, false on the server, for the parts of a component's script that only make sense where it attaches (timers, listeners onwindow, the DOM). Replacestypeof window !== 'undefined'; a window without a document (some server runtimes define one) counts as the server. #257class="…"on a component tag passes through to the component's top-level elements, after their own class and the scope class, so a parent's<style scoped>can style it ([#279](https://github.com/forinda/clarusjs/issues/279)). Islands keep it when they re-render a block in the browser. Only a staticclassfor now:[class]or{{ }}in it on a component is a located error. #281- A TypeScript 7.1 content mapper for
.tsclfiles: add"contentMappers": [{ "package": "clarusjs", "extensions": [".tscl"] }]totsconfig.json, and TypeScript (in VS Code, ortsc --runExternalCode) checks templates as you type, with errors, hover and completion in the template. It runs asclarusjs mapper. Template type checking (here and inclarusjs check) also types the untyped parameters of a script's own functions asany, so strict projects don't flag them. #234 clarusjs/forms: a headless forms engine.const f = form(values, { schema, show, messages })over a component's state or a store;<form [engine]="f">connects it. Every field's error (native constraints, a Standard Schema, server errors viaf.setErrors) shows in its[data-cl-message]element, witharia-invalidandaria-describedby, without naming the path in the template.f.error(path),f.errors,f.touched,f.changed,f.valid,f.pending,f.focus,f.reset; paths are type-checked. The compiler marks every[(value)]/[(checked)]withdata-cl-path. #261clarusjs/forms:f.reset(values)sets new values and makes them the starting point (a record loaded after the form was made, or saved and reloaded), sof.changed()andf.reset()compare against it. Also:[engine]connects its own element inside@forrows and next to nested islands (the same lookup reactive attributes use, now shared asmarked()in the runtime); a form's pending schema check stops when its last island goes; a form made over a store's signal is inert on the server. #268clarusjs/forms: multi-step forms on one page. Sections markeddata-cl-stepwith anidare shown one at a time, with the current one in the URL hash (Back/Forward and reload land on it; other hashes, like heading anchors, leave the form alone).f.next()checks the current step and stays with the first error focused,f.back()never checks,f.go(id),f.step, andf.steps(current, done, errors per step) for a step list.f.focus(path)opens the step holding the field. #262clarusjs/forms: submit takes you to the errors. A connected<form>'s submit (orf.submit()) checks everything, waits for the schema, and with errors goes to the step of the first one, focuses its field and shows them all (f.errorslists them with their message ids, for a summary). Otherwise it callssubmit(values); server errors it returns ({ errors: { path: message } }) land the same way. One submit at a time (f.submitting);show: 'submit'keeps errors hidden until the first one. #263parse(and theParsedFile,InputDecl,ImportDecl,TemplateNode,Attrtypes) fromclarusjs/compiler, so tools such as a language server can read a.tsclfile's syntax tree. #271- Explicit
<style scoped>and unique scope classes ([#279](https://github.com/forinda/clarusjs/issues/279)). - Breaking: a plain<style>is now global, plain CSS. Addscopedto keep a component's styles scoped to it. For now the compiler warns about a plain<style>, with its place; write<style global>to keep one global without the warning. - Every component's top-level elements carry a class unique to the component (cl-c-<name>-<hash>), merged with their ownclass. It replaces thedata-cl-cattribute.cl-c-is a reserved class prefix. - A parent's<style scoped>styles a child component's top-level element (by its class or tag), but not its inside. Parent rules no longer leak into a child component that has no<style>of its own. -compile()returnswarnings, locatedClarusErrors that aren't thrown. The Vite plugin prints them once per file. #280
Patch Changes
clarusjs check:$eventfor an event name the DOM doesn't know (a custom event like(rate)) is aCustomEvent, so$event.detailchecks; andstate([])starts an array of anything instead ofnever[](scripts are JavaScript, so there is nostate<string[]>([])). #224clarusjs checkcovers page sources: it reads the clarusjs plugin'ssources(Markdown pages from@clarusjs/content) andresolve.aliasfrom the app's Vite config. A component used in a.mdpage is checked like in a.tsclpage, with errors atpage.md:line:col; a page source's.load.tsis paired with it, and its views are in.clarusjs/views.d.ts. Root paths (/src/…) resolve as in Vite. #212- Type checking (
clarusjs checkand the content mapper):[attr]="…"on an element is checked against what it sets. A boolean attribute (by the DOM's own types:disabled,readonly,hidden, …) takes a boolean, since any string, even'false', switches it on; any other attribute takes a string, number, boolean or null, since an object would render as[object Object]. #245 clarusjs/forms: a field's message element is found in the nearest container around it that has one, so it can sit beside the label (<div data-cl-field><label>…</label> <input …> <small data-cl-message></small></div>) instead of inside it, where it would be read as part of the field's name.f.errorspaths are typed, so a summary can pass them tof.focus(). #264clarusjs/formsfixes from review: - Errors on paths no field shows (a whole-object schema rule, a server error like{ '': 'Server down.' }) stop submit and are listed inf.errors(with no id or step), instead of being dropped. -f.next()andf.submit()wait for the newest schema check (a pending pause is cut short), so a slow async rule can't be skipped; a schema that throws no longer leavesf.pendingstuck. - A field without its own[data-cl-message]no longer takes another field's. - Touched state follows the row, not its index: removing a touched row doesn't show the next row's error. - Back to the page as it loaded (no hash) shows the first step. #266- Type checking (
clarusjs checkand the content mapper): - An event handler or two-way binding inside@if (x)keeps that narrowing (xwas "possibly null" inside a(click)handler);@elsebranches know the earlier conditions were false. -$event.currentTargetis the element the handler is on (HTMLInputElementfor<input (input)>). - No errors from generated code undernoUnusedLocals(unread inputs,$index, helper types). #256 - Types in a
.tsclfile:@type Name<T> = …and@interface Name<T> extends … { … }, for the file's@inputprops. Any TypeScript type (unions, generics with defaults, mapped and conditional types,infer), continuing onto following lines while a bracket is open. Erased from compiled output; checked byclarusjs check, with errors at their line. Local to the file: other files see them only through the component's inputs.@inputtypes and defaults can span lines too (an object type, a default object), and function types keep their=>:@input onPick: (id: string) => void(the=of=>was read as the start of a default). #216 - Content mapper: an error on a whole construct underlines all of it (a missing prop underlines
<card, a two-way binding check[(open)]), not one character; and generated stand-ins (__cl_p) take no part in hover, completion or rename. #244 - Two-way binding into lists:
[(value)]="rows[$index].name"writes back copy-on-write (rows = rows.map(…)), so a field in a@forrow updates the list. Binding to the row variable itself ([(value)]="row.name"), which only changed the row's copy, is now a located error pointing to the index form. #222 clarusjs checkreports an unknown prop on a component that declares no@input(it was accepted silently), as it already did for components with inputs;render()fromclarusjs/viewschecks the same. #215- Event bindings for events that don't bubble work:
(mouseenter),(mouseleave),(pointerenter),(pointerleave),(load),(error),(scroll),(toggle),(invalid),(close),(cancel)and media events are caught in the capture phase, like(focus)and(blur)already were. #223 - Inputs are read-only and reactive, like
derived(). In an island, each input is a read-only signal: holes,@if/@for, effects andderived()that read it update when it changes. A nested island whose parent island passes it new props gets them in place (its DOM andstate()are kept) instead of being re-rendered. Assigning to an input is a compile error at its line (copy it to change it locally:let local = state(count)), andclarusjs checktypes inputs as deeply read-only, so changing anything inside one is a type error; a component's props accept read-only values. #218 - Fixes from review: -
[(value)]="form['name']"updates an object property (a bracket path used to assume an array). - A destructuring write to an input (({ value } = …)) is a located read-only error. - A multi-line generic type (Array<across lines) stays inside its@type. -(mouseenter)and other events that don't bubble run only their target's handler, not an ancestor's. - A@modelwrite is taken only by the island that binds that child, not by an outer one. - A nested island is kept in place only for the same component source. - New props are applied together (a newbatch()inclarusjs/runtime), so effects never see half an update. -clarusjs check: works through a symlinked project root; resolves aliased component imports (outside the project, and exact aliases to a.tsclfile); checks that a child's@modeltype can be written back into the parent's target. #231 - Fixes from review: - Forms: a component bound two ways more than once carries a path per binding (
data-cl-path-<model>on its island; its own fields write@<model>), so each binding's errors reach its field. A literal key (order['email']) is decoded in the path.formimported under another name keeps its state, and a local namedformis left alone. A schema that throws blocks submit. Values changed during a check are checked again before submit;next()checks the step's fields as they are after waiting; server errors for values changed while the server answered are dropped. - Type checking: enumerated attributes (draggable,spellcheck,translate) take their strings; a condition about an outer name isn't repeated inside a@forwhose item has that name. #233 - Type checking: a callback is typed
anyonly when passed to one of the script's own top-level functions (not a nested function that happens to share an imported name), and not when that parameter has a default, which gives the callback its type. #269 - The theme's templates type-check under strict TypeScript with the content mapper: its config types take readonly lists (a template's inputs are readonly, and mutable configs still fit), and its scripts narrow DOM lookups instead of assuming elements exist. Template type checking also types callbacks passed to a script's own functions (
record((p) => …)) asany, like those functions' own parameters. #235 - Content mapper: a template that doesn't parse (an unclosed
@if,<div>or{{while you type) still gives TypeScript for the rest of the file, so hover, completion and type errors keep working in the editor; the syntax error is reported as before. The build andclarusjs checkstay strict. #246 - Two-way binding.
[(value)]="form.name"on an<input>,<textarea>or<select>(and[(checked)]on a checkbox) shows a value and writes it back, copy-on-write (form = { ...form, name: value }), so a previous state is just the old value. On a component,[(x)]binds its@model xinput, the one kind of input a component may write: the write goes to the parent island (acl:modelevent), which updates its state and passes the value back in place; with no parent binding it, the component keeps the value.clarusjs checkrequires@model xfor[(x)]and a writable target. A reactive[value]/[checked]binding now also sets the property, so a field shows it after someone has typed. #221