@saolabs/client

Coordinated admin alpha compatibility: see release notes.

Runtime TypeScript phía trình duyệt của Saola: hydration HTML do Laravel render, state, component, điều hướng SPA và vòng đời tài nguyên.

Ngôn ngữ DB: Language System. App.Helper.text() đọc catalogs[locale] = { scope, revision, messages: tree }; installLanguage/loadLanguage nạp/thay snapshot lúc chạy. changeLanguage(locale, loader, guard) kiểm form trước/sau fetch, bỏ yêu cầu cũ rồi chuyển locale. Page-data i18n cập nhật snapshot trước render, cùng scope giữ locale đã chọn. Legacy messages.json/groups dành cho trans/choice và helper __ gọi trực tiếp; compiler mới hạ __() trong .sao xuống text().

Form có thể dùng App.Router.addNavigationGuard(guard) để bổ sung guard mà giữ beforeEach của host; API trả disposer. Gỡ guard khi pause/destroy, đăng ký lại khi resume. false chặn trước mount/history; Back bị chặn khôi phục URL cho cả history/hash. Guard này độc lập guard đổi ngôn ngữ; xem Settings renderer về draft, CSRF và lifecycle.

Bắt đầu

npm install @saolabs/client
npm install --save-dev @saolabs/builder typescript
composer require saola/core saola/compiler

Viết giao diện bằng .sao, để compiler sinh class View và registry. Bắt đầu với hướng dẫn component trong workspace hệ sinh thái. Compiler PHP sinh Blade SSR; client nhận DOM và xử lý tương tác trong browser.

Module và tương thích

Package phát hành ESM. Các entry công khai:

• @saolabs/client: runtime, services và kiểu dữ liệu.
• @saolabs/client/plugins: createPlugin, pluginManager.
• @saolabs/client/testing: mount, mountView, nextFrame và Harness.

import { HttpService } from '@saolabs/client';
import { createPlugin, pluginManager } from '@saolabs/client/plugins';

const http = new HttpService();
pluginManager.register(createPlugin('example', () => {
    http.setTimeout(5000);
})).install('example');

Các công cụ CommonJS dùng await import('@saolabs/client'); package không cam kết require() đồng bộ. Runtime cần DOM (browser hoặc jsdom trong test), không phải renderer SSR chạy trong Node. Dùng PHP compiler cho SSR Laravel. Các import tương đối có đuôi .js; build và declaration được kiểm với NodeNext.

Test component đã compile

import { mount, nextFrame } from '@saolabs/client/testing';
import Counter from './compiled/counter.js';

const counter = mount(Counter, {initial: 3});
counter.container.querySelector('button')?.click();
await nextFrame();
console.log(counter.text());
counter.destroy();

Chạy trong môi trường DOM. Với theme nạp rời, externalize @saolabs/client để app và theme dùng cùng một runtime; xem bootstrap.

Phát triển và kiểm chứng

npm run build          # ESM JS và declarations
npm run typecheck      # Kiểm source, không emit
npm test               # Runtime + compile-to-mount contract tests
npm run test:package   # Standalone boot/catalog/navigation checks, không cần sibling/PHP
npm run check-exports  # Pack thật; kiểm 3 entry và types trong consumer tạm

check-exports không publish. Nó kiểm native ESM, dynamic import từ CommonJS, mount view qua package đã đóng và TypeScript NodeNext, không dùng alias source. Bộ test compile fixture cần sibling builder/, compiler/, saola/, admin/ trong workspace hệ sinh thái. Thiếu builder là lỗi kiểm tra, không tự bỏ qua test.

GitHub Actions kiểm package trên Node 20/22/24: typecheck, build, đối chiếu dist đã commit, test:package và consumer từ tarball thật. Bộ npm test đầy đủ vẫn chạy trong workspace hệ sinh thái; CI package không thay thế kiểm SSR/admin đó.

Tài liệu

• Runtime API
• Compiler contract
• Testing
• Devtools

MIT.