npm package: @miurajs/miura
Description: The main package for the miura framework, bundling all core modules.
Author: Fernando Alves
Latest version: 2.4.12

# `@miurajs/miura`

The main package for the miura framework.

This package bundles and exports all the core modules, making it easy to get started with miura.

## Included Building Blocks

- `MiuraElement` for reactive custom elements
- `html` and `css` template utilities
- property, state, and computed reactivity
- structural directives and fine-grained bindings
- component-scoped async resources with `$resource()`
- component-scoped form state with `$form()`
- lightweight shared state with `$shared()`
- tree-scoped dependency injection with `$provide()` and `$inject()`
- router bridge helpers with `$route()`, `$routeSelect()`, and `$routeData()`
- route-driven async state with `$routeResource()`
- island hydration helpers with `$islandProps()` and `$islandResource()`
- integrated debugger runtime with framework-level dev overlays and component layers
- signals and shared reactive primitives

## Example

```typescript
import { MiuraElement, html, component } from '@miurajs/miura';

@component({ tag: 'app-user-card' })
class AppUserCard extends MiuraElement {
  user = this.$resource(() => fetch('/api/user').then((r) => r.json()));

  template() {
    return this.user.view({
      pending: () => html`<p>Loading...</p>`,
      ok: (user) => html`<p>${user.name}</p>`,
      error: (error) => html`<p>${String(error)}</p>`
    });
  }
}
```

```typescript
@component({ tag: 'app-signup-form' })
class AppSignupForm extends MiuraElement {
  form = this.$form({ email: '', acceptedTerms: false });

  template() {
    const email = this.form.field('email');

    return html`
      <form @submit=${this.form.handleSubmit(async (values) => {
        console.log(values);
      })}>
        <input &value=${email} @blur=${email.touch}>
        <input type="checkbox" &checked=${this.form.field('acceptedTerms')}>
        <p>${email.showError ? email.error ?? '' : ''}</p>
      </form>
    `;
  }
}
```

Async validation is also supported through `validateAsync`, and is automatically respected by `submit()` / `handleSubmit()`. Automatic modes are opt-in through `validateAsyncOn: 'blur' | 'change'`.

Resources can also participate in shared async caching through `key`, which gives you cache reuse, in-flight dedupe, and explicit invalidation with helpers like `resourceKey(...)`, `invalidateResource(...)`, and `invalidateResourceNamespace(...)`.
They also support `staleWhileRevalidate`, plus `staleTime` / `cacheTime` cache policy control.

Forms also keep submit outcome state through `submitError`, `submitResult`, and `submitSucceeded`, which helps keep success/error UI close to the form primitive instead of in separate component state.

Server-side field validation can also be mapped back into the form with `setErrors()`.
For submit flows, `failSubmit()` can capture the submit error and field errors together.
`view()` can render submit-state UI declaratively from the form itself.
Nested field paths like `profile.name` and `profile.meta.featured` are supported too.

For lightweight cross-component state, `$shared(key, initial)` gives multiple components the same signal instance without requiring a full store setup. Use namespaced keys like `blog-editor:theme`, `sharedKey(...)`, or `createSharedNamespace(...)` to avoid collisions.

For parent-to-descendant dependencies, use `createContextKey(...)` with `$provide()` and `$inject()` instead of reaching for shared global keys. Context stays tree-scoped, and the nearest provider wins. When descendants should react to changes, provide a signal or another reactive primitive as the context value.

Route-driven resources now bridge cleanly with router loaders too: `$routeResource()` can derive route-based cache keys automatically and hydrate from route data before revalidating.
`$routeData()` can also return the full loader data object when you omit the key, and `hydrateFromRouteData: true` lets a route resource hydrate from that full payload directly.
Islands can do the same on the server/client boundary with `$islandProps()` and `$islandResource()`, so server payloads can hydrate directly into component state before optional client revalidation.

When you build on `MiuraFramework`, the debugger can be enabled centrally from `static config.debugger` during development. Individual components can then refine their own debug presentation with `static debug` or `@debug(...)`, for example to rename a layer label or opt out of reporting in a noisy internal helper component. The debugger runtime logger is exported here as `debugLogger` so it stays distinct from the component decorator.

See [@miurajs/miura-element](/Users/fernandoalves/Desktop/_dev/miura-js/packages/miura-element/README.md) for the component API and [docs](/Users/fernandoalves/Desktop/_dev/miura-js/docs/README.md) for the broader framework documentation.