Client components

A .pkc file is a client-side reactive component that compiles to a native Web Component with shadow DOM encapsulation. This page documents the file format and the runtime surface. For task recipes see the reactivity how-to and events how-to.

File structure

A .pkc file has three sections: <template>, <script lang="ts">, and <style>.

<template name="pp-counter">
    <div>
        <p>Count: {{ state.count }}</p>
        <button p-on:click="increment">Increment</button>
    </div>
</template>

<script lang="ts">
    const state = {
        count: 0 as number,
    };

    function increment() {
        state.count++;
    }
</script>

<style>
    div { padding: 1rem; border: 1px solid #eee; }
</style>

Template attributes

The enable attribute accepts a single value. Components that need both behaviours can declare them by listing both names separated by whitespace (enable="form animation").

Project components use the reserved pp- prefix to avoid collisions with built-in and third-party custom elements.

Script attributes

Runtime roots in scope

A reactive <script lang="ts"> block in a PKC file has three runtime roots available without import:

Reactive state

A const state = { ... } declaration inside <script> defines the reactive scope. Writes to its properties trigger a re-render. Arrays and objects nested in state are also reactive: push, splice, and property assignment all trigger updates.

const state = {
    count: 0 as number,
    name: 'Guest' as string,
    is_active: false as boolean,
    items: [] as string[],
    user: null as { name: string; email: string } | null,
};

Variables declared outside the state object are not reactive: a let count = 0 outside state compiles and mutates but does not trigger re-renders.

Naming and attribute mapping

State field names map to HTML attributes through propertyToAttributeName:

snake_case field names round-trip without transformation. camelCase field names lower to kebab-case attribute names. Components in components/m3e/ use camelCase for historical reasons.

For the rationale see about reactivity.

Type annotations

Each state field carries an as TypeName annotation. The compiler reads the annotation to emit a static propTypes getter, which the runtime uses to coerce attribute strings back to typed values. Authors must annotate fields when the initialiser is null (ambiguous between null | number and null | string). Annotations are optional when the initialiser is itself typed ('Hello' infers String, 0 infers Number, false infers Boolean). The convention is to annotate every field for clarity.

State and HTML attribute binding

The runtime binds state bidirectionally to the host element's HTML attributes:

Sync flags (applyingToState, reflectingToAttribute, initialising) prevent loops. A state-write-then-attribute-write does not trigger another state-write.

Reflection scope. Only primitive types auto-reflect: string, number, boolean. Arrays, objects, and JSON-typed fields stay internal unless explicitly opted in via the metadata system.

Boolean semantics. Attribute presence is the truth signal:

Writing state.flag = false removes the attribute via host.toggleAttribute. The DOM never carries flag="false".

Null semantics. Writing null or undefined to any state field removes the attribute. A field declared as string | null round-trips null faithfully. A non-nullable field falls back to its default when the attribute is absent.

This binding is the primary inter-component communication channel. A PKC drives another PKC by calling setAttribute on it. A .pk script drives any PKC the same way. See about reactivity for the design rationale.

Props

There is no separate const props declaration. Reactive state declared in const state = { ... } is the single source for both internal mutable values and externally driven props. The compiler reads each field's as Type annotation and emits a static propTypes getter. The runtime uses that getter to coerce attribute strings to typed values when external code calls setAttribute on the host element.

const state = {
    label: '' as string,
    variant: 'primary' as 'primary' | 'secondary',
    is_disabled: false as boolean,
};

Parent templates pass values through plain HTML attributes:

<pp-button label="Save" variant="primary" is_disabled></pp-button>

Primitive-typed state fields (string, number, boolean) reflect bidirectionally to HTML attributes via the binding described in State and HTML attribute binding. Arrays, objects, and JSON-typed fields stay internal unless opted in via the metadata system.

Directives

.pkc templates support the directives described below. See the directives reference for full syntax.

Lifecycle hooks

Register lifecycle callbacks by calling registration methods on pkc inside the <script> body. Every hook is optional and additive. Calling the same registration method multiple times queues multiple callbacks that all fire in order.

pkc.onConnected(() => {
    window.addEventListener('scroll', handleScroll);
    handleScroll();
});

pkc.onDisconnected(() => {
    window.removeEventListener('scroll', handleScroll);
});

pkc.onUpdated((changedProperties) => {
    if (changedProperties.has('count')) {
        piko.bus.emit('counter:changed', { count: state.count });
    }
});

Slots

Slot APIs available on pkc (the host element):

pkc.attachSlotListener('', (elements) => {
    for (const tab of elements) {
        tab.toggleAttribute('selected', tab.getAttribute('value') === state.active);
    }
});

A PKC drives its slotted children by setting their HTML attributes. When a slotted element is itself a PKC, those attribute writes feed through to its reactive state via the binding described in State and HTML attribute binding.

Events

piko.event.dispatch(this, 'pp-counter:change', { count: state.count });
piko.bus.emit('cart:updated', { item_count: 3 });

For when to choose each surface, see about reactivity.

Shadow DOM and styling

The compiler scopes <style> to the shadow root by default. Styles do not leak out, and outer page styles do not leak in.

Form association

Add enable="form" to the <template> to participate in forms. The component then responds to:

• form.elements[name] lookup.
• Validation (checkValidity(), reportValidity()).
• formdata submission.
• reset events.

Inside the component, call piko.form.setValues(formSelector, values) to set form field values programmatically. Pass either a CSS selector or an HTMLFormElement plus a record of field names to values.

piko.form.setValues('#edit-user', {
    name: 'John Doe',
    email: '[email protected]',
});

Registration

The CLI scans the project's components/ directory by default. The compiler picks up locally authored .pkc files automatically. piko.WithComponents registers components shipped by external Go modules.

ssr := piko.New(
    piko.WithComponents(
        piko.ComponentDefinition{
            TagName:    "pp-counter",
            SourcePath: "components/pp-counter.pkc",
            ModulePath: "github.com/myorg/piko-components",
            IsExternal: true,
        },
    ),
)

ComponentDefinition fields:

See also

• How to reactivity.
• How to events.
• How to event bus for cross-component messaging.
• Directives reference.
• Scenario 003: reactive counter, Scenario 007: todo app, Scenario 009: form wizard.

Integration tests: tests/integration/pkc_serving/, tests/integration/asset_pipeline/.