@ivanlog/gs

Universal DOM/state runtime for GS-generated TypeScript browser applications.

Generated projects import @ivanlog/gs for typed DOM wrappers, template component instances, gs-ctrl controls, injected slots, forms, state routing and the common application model. GS 2.0 adds AppBrowser, universal states, layouts and typed adoption of server-rendered DOM. SSR is supplied by the companion @ivanlog/gs-server package.

Install

npm install @ivanlog/gs

TypeScript Usage

Generated GS code normally imports the package as a namespace:

import * as gs from "@ivanlog/gs";

const root = gs.w(document.querySelector("#app"));
const items = gs.q(".item");

The package exposes compiled JavaScript in bin/** and TypeScript declarations in bin/**/*.d.ts.

External Browser Runtime

Browser artifacts are produced by esbuild during npm run build:all and npm pack, then published in browser/**. The generated folder is not repository source. New applications can keep GS outside their frequently changing application bundle by externalizing @ivanlog/gs and mapping it to the ESM browser entry:

<script type="importmap">
{
  "imports": {
    "@ivanlog/gs": "/js/gs.min.js"
  }
}
</script>
<script type="module" src="/js/app.js"></script>

The project build copies the exported @ivanlog/gs/browser artifact from its pinned npm dependency to /js/gs.min.js. Production builds should give that file a content fingerprint or its immutable npm package version and serve it like the other static files under htdocs; npm and node_modules are not exposed at runtime.

The compatibility bundle remains available for applications that intentionally use a global API:

<script src="./node_modules/@ivanlog/gs/browser/gs.min.js"></script>

That compatibility bundle registers its public API on globalThis.gs. The ESM @ivanlog/gs/browser artifact and the normal package entrypoint do not create a global variable.

An application that bundles npm modules but still needs the legacy global can opt into it explicitly:

import "@ivanlog/gs/browser-global";

Browser and server applications

Projects define separate final classes over AppBrowser from this package and AppServer from @ivanlog/gs-server. Both use the same DI and explicit state registration model. Universal states can be registered in both; private or unported states remain browser-only.

The shared HTML shell should contain one <main gs-app></main> mounting root. Browser rendering and server composition use that same root selector.

The server runtime is a separate package so browser code and dependencies contain no SSR or Node implementation:

import { AppServer, serve } from "@ivanlog/gs-server";

It requires Node 18 or newer for native fetch, Request and Response.

GS SSR is anonymous-only. Private/authenticated states stay in the browser application; credential-bearing requests bypass the HTML cache and their authorization/cookie headers are not exposed to server state code.

The repository includes a GS 2.0 guide and runnable example, but this package README is intentionally self-contained.

Main Runtime Areas

• WrapperGS - central DOM wrapper with cached instances, class/tag based wrapper extension, DOM operations, state helpers, data-* and gs-* helpers.
• TemplateGS - template lookup and component construction for generated <template gs-tmpl="..."> fragments.
• GS - query wrapper used by gs.q(selector) for batch DOM operations.
• App, AppBrowser - compact application roots for DI, lifecycle and browser settings. AppServer belongs to @ivanlog/gs-server.
• StateGS, StatePagedGS - shared query/path routing and page-bearing state lifecycle.
• State head management - shared SSR/browser title, description, robots, canonical, Open Graph, alternate-link and JSON-LD reconciliation through StateGS.
• LayoutGS, GuiBrowserGS - reusable layouts, browser registration and access to active layout/page instances. Server composition remains internal.
• EventsGS - typed sync/async event helpers.
• FormGS - form value collection, filling and validation.
• com/** - wrappers for forms, inputs, files, textarea, select, option, anchor, label, dialog, details, progress, meter, image, toggles and box controls.
• ctrls/** - declarative, form-independent gs-focus keyboard navigation.
• helpers/** - browser helpers for HTML, arrays, dates, files, blobs, images, text, validation, localization, cookies, URLs and crypto utilities.

gs.generators.createPassword() creates a cryptographically secure 16-character password without visually ambiguous characters; createHexString() creates 32 lowercase hexadecimal characters by default. Both accept an explicit non-negative length and require crypto.getRandomValues.

gs.localization defaults to English, accepts arbitrary normalized language codes and provides setLangAndReload(...) for the full rebuild required by template-localized pages. Validation catalogs follow the active browser/server request language; English and Russian are included and applications can register complete additional catalogs.

Generated Template Integration

GS template tooling generates TypeScript classes that expect this package:

import * as gs from "@ivanlog/gs";

At runtime, WrapperGS reads template metadata such as gs-tmpl, gs-ctrl and gs-ins, builds typed controls, and resolves injected components.

Notes

• The main entry is universal/browser-safe; SSR and Node hosting are published as @ivanlog/gs-server.
• globalThis.gs is assigned only by the compatibility browser bundle or the explicit @ivanlog/gs/browser-global entrypoint. Importing the main package or the ESM browser runtime does not mutate the global object.
• ESM and compatibility browser artifacts are produced with esbuild.
• The package does not include the GS template generator CLI. That tool is distributed separately as Ivanlog.GS.Templates.Tool.