khnum_maat library

Wires khnum into the Maat framework.

Classes

AttributeBag

The attributes bag a component receives: every attribute that was not declared in @props. Rendering it emits key="escaped value" pairs.

ComponentAttribute

One attribute on a component tag.

ComponentNode

<x-name attr="..." :attr="expr">body<x-slot name="s">...</x-slot></x-name>

DirectiveNode

A developer-registered directive: @money(price).

EchoNode

{{ expr }} (escaped) or {!! expr !!} (raw).

Expression

A parsed expression from {{ }}, @if(), :attr="" and friends.

FileTemplateLoader

Loads name.with.dots from <viewsPath>/name/with/dots<extension>. Names under components. resolve against componentsPath when set.

ForNode

@for (final item in items) ... @endfor.

HtmlString

Marks a string as already-safe HTML so {{ }} will not escape it. Construct it only around markup you produced yourself or already sanitised.

IfBranch

IfNode

@if/@elseif/@else/@endif.

IncludeNode

@include('view') / @include('view', {data}).

Khnum

The template engine. Create one per application, register functions and directives at startup, then call render per request.

MemoryTemplateLoader

Templates from a map; handy for tests and for binaries that embed views.

Node

ParentNode

@parent inside a section: splice in the layout's content.

PropsNode

@props({"type": "info"}) at the top of a component template.

RenderContext

The variables visible while rendering one template, plus the services an expression needs (member resolution, registered functions). Loops and components open child contexts; lookups fall through to the parent frame.

SectionNode

@section('name') ... @endsection, @section('name', expr), and @section('name') ... @show (yieldsImmediately).

TailwindBinary

Locates — downloading once if needed — the Tailwind CSS standalone CLI.

TailwindCommand

Compiles the application's CSS with the Tailwind standalone CLI.

Template

A parsed template. The AST is the contract between the parser and the renderer: any parser that produces these nodes works with the renderer.

TemplateLoader

Where templates come from. Implement to load from a database, assets bundled in a binary, and so on.

TemplateSource

The raw text of one template plus a version that changes when the source does (mtime for files), so development mode can reload.

TextNode

View

Static conveniences over the bound engine, the View facade.

ViewServiceProvider

Binds a Khnum engine built from config('view'):

YieldNode

@yield('name') / @yield('name', default).

Enums

TemplateEnvironment

Controls reloading: development re-reads a template whose file changed; production parses each template once and never touches the disk again.

Functions

escapeHtml(Object? value) → String

HTML-escape value for use in element content and attribute values. null becomes ''; an HtmlString passes through unchanged.

normalizeViewName(String name) → String

Rejects anything that is not dot-separated identifiers, so ../etc/passwd never reaches the filesystem. / is accepted as a separator alias.

renderView(String name, [Map<String, Object?> data = const {}]) → Future<String>

Renders name ('tasks.index' → resources/views/tasks/index.khnum.html) with data and returns the HTML.

toJsonHtml(Object? value) → HtmlString

JSON for use inside <script>: <, >, & and U+2028/2029 are escaped as \uXXXX so </script> inside a string cannot break out. Returned as an HtmlString so {{ json(data) }} prints it verbatim.

view(String name, [Map<String, Object?> data = const {}]) → Future<Response>

Returns an HTML response for the rendered template. For another status wrap renderView yourself: Response.html(await renderView('form', data), status: 422).

viewCommands() → List<Command>

The view layer's maat commands. Register the result in lib/app/console/kernel.dart, alongside databaseCommands(...).

Typedefs

BinaryChmod = Future<int> Function(String path)

Marks path executable, returning the process exit code. Injected so tests can simulate a chmod failure without a real broken filesystem.

BinaryDownloader = Future<void> Function(Uri url, File target)

Fetches url into target. Injected so tests never touch the network.

DirectiveHandler = Object? Function(RenderContext context, List<Object?> arguments)

A custom directive: @money(price). Receives the evaluated arguments and the current RenderContext; whatever it returns is written unescaped, so call escapeHtml on anything that came from a user.

Helper = TemplateFunction

PropertyResolver<T> = Object? Function(T value, String key)

Resolves value.key for objects that are neither maps nor toJson() classes. Return null for an unknown key.

TailwindProcessRunner = Future<int> Function(String executable, List<String> arguments)

Runs the Tailwind binary. Injected so tests assert the argv without executing an 80 MB download.

TemplateFunction = Object? Function(List<Object?> arguments)

A Dart function templates may call: {{ upper(name) }}.

Exceptions / Errors

TemplateException

Base class for every error khnum raises. Always carries the template name and the 1-based line where the problem is, when known.

TemplateNotFoundException

The view name does not map to a file, or is not a legal view name.

TemplateRenderException

Runtime failure while rendering: function threw, bad operand types, include recursion past Khnum.maxDepth.

TemplateSyntaxException

Malformed template source: unclosed {{, unknown @endfoo, bad expression.

UndefinedVariableException

A variable or key referenced by a template is not in the data.