@electral-io/webspa 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,711 @@
-# Temporary Holding Version
+# @electral-io/webspa
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A no-HTML, TypeScript-first Single Page Application framework built on native Web Components, with an OpenLayers-based GIS layer in the same package. Build data-rich business UIs and map apps entirely in code: no templates, no JSX, no framework lock-in.
+
+Coming from the previous two separate packages (core and GIS)? See [MIGRATION.md](MIGRATION.md).
+
+> The exact API of the version you installed is in `node_modules/@electral-io/webspa/dist/index.d.ts` (core and GIS exports share the same entry). Examples below follow the current source (`src/`; GIS in `src/gis/`).
+
+## Table of Contents
+
+- [Installation](#installation)
+- [TypeScript & Parcel Configuration](#typescript--parcel-configuration)
+- [Styles & Theme](#styles--theme)
+- [CSS Variables](#css-variables)
+- [CSS Helper Classes](#css-helper-classes)
+- [IconClass](#iconclass)
+- [Core Utilities](#core-utilities)
+- [Components](#components)
+- [Framework & Dependency Injection](#framework--dependency-injection)
+- [Application Startup](#application-startup)
+- [GIS (map apps)](#gis-map-apps)
+- [Development](#development)
+- [Release](#release)
+- [Claude Code skill](#claude-code-skill)
+
+---
+
+## Installation
+
+```bash
+npm install @electral-io/webspa
+```
+
+One dependency covers both the core framework and the GIS layer. Parcel apps (geotiff comes in through `ol`) must also add `"alias": { "zstddec/stream": false }` to the **app's** package.json, otherwise the build fails with `Failed to resolve 'zstddec/stream'` (Parcel ignores `alias` in dependencies). Map apps additionally need `ol` (OpenLayers 10) in the app, see [GIS](#gis-map-apps).
+
+---
+
+## TypeScript & Parcel Configuration
+
+Decorators drive dependency injection and component registration. `tsconfig.json` **must** include:
+
+```json
+{
+  "compilerOptions": {
+    "target": "es2019",
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "useDefineForClassFields": false
+  }
+}
+```
+
+- `emitDecoratorMetadata` lets `@Inject()` resolve the field type at runtime through `reflect-metadata`.
+- `useDefineForClassFields: false` keeps class fields from overwriting the `@Inject()` getters.
+
+With Parcel, compile TypeScript with `tsc`, because the default SWC transform does not emit decorator metadata. Add the glob resolver so the entry file can import whole folders:
+
+```json
+{
+  "extends": "@parcel/config-default",
+  "resolvers": ["@parcel/resolver-glob", "..."],
+  "transformers": { "*.{ts,tsx}": ["@parcel/transformer-typescript-tsc", "..."] }
+}
+```
+
+---
+
+## Styles & Theme
+
+Importing the package once in your entry point loads everything: Bootstrap Icons, the Tabulator base CSS, the theme (Google Sans Flex font, design tokens, element and form styles), the helper classes and the GIS / OpenLayers styles (`dist/index.css`).
+
+```ts
+import { /* anything */ } from '@electral-io/webspa';
+```
+
+### Overriding the theme
+
+Override the tokens in your own stylesheet:
+
+```css
+:root {
+  --primary: var(--teal-600);
+  --primary-2: var(--cyan-600);
+  --secondary: var(--violet-600);
+  --font-family: "Roboto";
+  --spacing: 6px;          /* every spacing / padding / radius token derives from this */
+}
+```
+
+Users can also pick colors at runtime from `ApplicationProperties.themes`.
+
+### Dark / light mode
+
+```ts
+document.documentElement.setAttribute('data-theme', 'dark');   // or 'light'
+```
+
+The theme switches its tokens under `:root[data-theme="dark"]`. Components styled only with tokens get dark mode for free, so avoid hard-coded colors.
+
+### CSS variables IntelliSense
+
+Add this to your project's `.vscode/settings.json` to get autocompletion for every token:
+
+```json
+{
+  "css.customData":  ["./node_modules/@electral-io/webspa/dist/web-spa-css-custom-data.json"],
+  "less.customData": ["./node_modules/@electral-io/webspa/dist/web-spa-css-custom-data.json"],
+  "scss.customData": ["./node_modules/@electral-io/webspa/dist/web-spa-css-custom-data.json"]
+}
+```
+
+The file is generated from the theme sources by `npm run css-data` (it is written to `static/` and copied into `dist/` on build). Run it after changing `src/style/theme/*.less`.
+
+---
+
+## CSS Variables
+
+The source of truth is `src/style/theme/main.less` (or `dist/web-spa-css-custom-data.json` in the package).
+
+### Brand
+
+| Variable | Default | Use |
+|---|---|---|
+| `--primary` | `#2563EB` | Theme color (the theme menu overrides it): accents, active state |
+| `--primary-2` | `#1D4ED8` | Second theme color (gradients) |
+| `--action` / `--action-hover` / `--action-soft` | `= --primary` | Primary action color (buttons, links, active chip), its hover state and a light tint |
+| `--brand` / `--brand-soft` | `#123C3A` / `#E7F0EF` | Fixed corporate color (side rail, group headers, active sub-tab); does not follow the theme menu |
+| `--primary-inverse` | `--white` | Text on a primary or colored background |
+| `--secondary` | `--fuchsia-600` | Secondary brand color |
+| `--secondary-inverse` | `--white` | Text on a secondary background |
+| `--mid` | `--gray-500` | Neutral mid tone |
+| `--primary-hover` / `--primary-focus` | computed | Hover and focus tints of primary |
+| `--secondary-hover` / `--secondary-focus` | computed | Same for secondary |
+| `--accent-bg-img` / `--accent-bg-img-v` | gradient | Primary to primary-2 gradient (horizontal / vertical) |
+
+### Surfaces & text (light / dark)
+
+| Variable | Use |
+|---|---|
+| `--base-up` / `--base-down` | Foreground / background direction (`#222`/`#FFF` light, `#fff`/`#111` dark) |
+| `--bg-main` | Application background behind panels |
+| `--bg-card` | Card / panel surface |
+| `--background-color` | Element background (= `--base-down`) |
+| `--navside-color` | Dark side navigation chrome |
+| `--text` / `--text-color` / `--color` | Body text |
+| `--text-2` | Secondary text |
+| `--text-muted` | Hints, captions, placeholders |
+| `--text-table` | Table cell text (= `--text-2`) |
+| `--divider` | Thin separators (grid row dividers) |
+| `--row-selected` | Selected table row |
+| `--text-mark` | Search-match highlight background |
+| `--hover-color` | Hovered row / item background |
+| `--selected-color` | Selected row / item background |
+| `--active` | Active outline color |
+| `--h1-color` … `--h6-color` | Heading colors, progressively tinted with primary |
+
+### State colors
+
+| Variable | Use |
+|---|---|
+| `--danger`, `--warning`, `--success`, `--info` | State colors |
+| `--danger-2`, `--warning-2`, `--success-2`, `--info-2` | Softer tints |
+| `--{state}-u1` … `-u3` | State color mixed toward `--base-up` (text direction, stronger contrast) |
+| `--{state}-d1` … `-d3` | State color mixed toward `--base-down` (background direction, soft fills) |
+| `--danger-soft`, `--warning-soft`, `--success-soft` | Light badge / pill backgrounds |
+| `--ico-fg-{state}` / `--ico-bg-{state}` | Icon badge foreground / background |
+
+Example: a soft warning box is `background: var(--warning-soft); color: var(--warning-u2); border-color: var(--warning)`.
+
+### Borders, shadows, motion
+
+| Variable | Default | Use |
+|---|---|---|
+| `--border-color` | `#E2E8F0` light / `#1E293B` dark | Border color |
+| `--border-width` | `1px` | Border width |
+| `--border` | `var(--border-width) solid var(--border-color)` | Border shorthand |
+| `--border-radius` | `var(--spacing)` | Inputs / buttons radius |
+| `--radius-card` / `--radius-pill` | `12px` / `999px` | Card / panel and pill radius |
+| `--control-h` / `--control-h-form` / `--control-h-sm` | `36px` / `40px` / `28px` | Toolbar, form input and small control heights |
+| `--outline-width` | `2px` | Focus outline |
+| `--focus-color` | `--primary-focus` | Focus ring |
+| `--shadow-color` / `--shadow-color-lg` | | Shadow base colors |
+| `--drop-shadow` / `-m` / `-r` / `-lg` | | Small, medium, top (reversed) and large shadows |
+| `--transition` / `--transition-slow` | `0.25s` / `0.5s` | Standard transitions |
+| `--modal-overlay-background-color` / `--modal-overlay-backdrop-filter` | | Modal backdrop |
+
+### Spacing & typography
+
+| Variable | Default | Use |
+|---|---|---|
+| `--spacing` | `8px` | Base unit |
+| `--spacing-half` / `--spacing-1-5x` / `--spacing-2x` / `--spacing-2-5x` / `--spacing-3x` | `4` / `12` / `16` / `20` / `24px` | Spacing scale |
+| `--panel-spacing` | `12px` | Panel inner padding |
+| `--pad` / `--pad-half` / `--pad-2x` | shorthands | Padding presets (vertical horizontal) |
+| `--font-family` | `"Google Sans Flex 24pt"` | Base font |
+| `--font-mono` | `"IBM Plex Mono"` | Ids, codes (bundled font) |
+| `--font-size` | `13px` | Base font size |
+| `--fs-xs` … `--fs-xl` | `0.75rem` … `1.25rem` | Font size scale |
+| `--fs-grid-header` / `--fs-card-title` | `12px` / `16px` | Table header / card title |
+| `--font-weight`, `--line-height` | | Base weight / line height |
+
+### Form elements
+
+`--form-element-color`, `--form-element-background-color`, `--form-element-border-color`, `--form-element-focus-color`, `--form-element-active-background-color`, `--form-element-active-border-color`, `--form-element-disabled-background-color`, `--form-element-disabled-border-color`, `--form-element-disabled-opacity`, `--form-element-placeholder-color`, `--form-element-spacing-vertical`, `--form-element-spacing-horizontal`, `--form-label-font-weight`, `--form-element-invalid-border-color` / `-active-border-color` / `-focus-color`, `--form-element-valid-border-color` / `-active-border-color` / `-focus-color`.
+
+### Color palette
+
+The full Tailwind palette (OKLCH) is available as `--{color}-{shade}`.
+
+- **Colors**: `red`, `orange`, `amber`, `yellow`, `lime`, `green`, `emerald`, `teal`, `cyan`, `sky`, `blue`, `indigo`, `violet`, `purple`, `fuchsia`, `pink`, `rose`, `slate`, `gray`, `zinc`, `neutral`, `stone`.
+- **Shades**: `50`, `100` … `900`, `950`.
+- Also `--black` and `--white`.
+
+Use palette colors to define your own tokens. Use the semantic tokens above in components, because palette colors do not switch with dark mode.
+
+---
+
+## CSS Helper Classes
+
+| Class | Effect |
+|---|---|
+| `.wh-100`, `.w-100`, `.h-100` | 100% width and/or height |
+| `.grid-100`, `.grid-100-of` | Full-size grid (`-of`: overflow hidden) |
+| `.scrollable` | Full-size `overflow: auto` |
+| `.flex-v`, `.flex-h` | Flex column / row |
+| `.gap` | `gap: var(--spacing)` |
+| `.centerContent` | Full-size, content centered |
+| `.inline-titled` | Inline row, centered, half gap (label + control) |
+| `.panel-container` | Full-size padded scrollable panel body |
+| `.pad-h`, `.pad`, `.pad-2x` | Padding `--spacing-half` / `--spacing` / `--spacing-2x` |
+| `.border`, `.borderrd` | Form border / form border + radius |
+| `.hide` | `display: none !important` |
+| `.clickable` | Pointer cursor + hover fade |
+| `[disabled]`, `.disabled`, `[restricted]` | Dimmed, not-allowed cursor |
+| `[active]` | `--active` outline |
+| `.fg-primary`, `.fg-secondary`, `.fg-danger`, `.fg-warning`, `.fg-success`, `.fg-info` | Text color |
+| `.bg-primary`, `.bg-secondary`, `.bg-danger`, `.bg-warning`, `.bg-success`, `.bg-info` | Background + inverse text |
+| `.alert.alert-warning` | Warning box |
+| `.f-large` | `font-size: large` |
+
+---
+
+## IconClass
+
+Typed Bootstrap Icons class strings.
+
+```ts
+import { IconClass } from '@electral-io/webspa';
+
+IconClass.save;              // 'bi bi-floppy2-fill'
+IconClass.get('buildings');  // 'bi bi-buildings', any Bootstrap icon id (typed as BootstrapIconsId)
+```
+
+Presets include `search`, `query`, `save`, `add`, `new`, `delete`, `edit`, `cancel`, `X`, `error`, `warning`, `info`, `success`, `chevron_*`, `caret_*`, `dots`, `dots_v`, `logout`, `settings`, `world`, `alert`, `hand`, `zoom_in`, `zoom_out`, `cursor`, `key`, `layers`, `person`, `people`, `pin*`, `image`, `book`, `download`, `bbox`, `circle`, `clock`, `clock_history`, `crosshair`, `email`, `eye`, `eye_slash`, `flag`, `journal`, `lightning`, `calendar`, `list`, `map`, `map_fill`, `paperclip`, `pinmap`, `puzzle`, `question`, `refresh`, `light`, `dark`, `palette`.
+
+---
+
+## Core Utilities
+
+### Result types
+
+```ts
+type OpResult<T = void> = { success: boolean; message?: string; data?: T };
+type AsyncOpResult<T = void> = Promise<OpResult<T>>;
+interface ILookup { key?: string | number; title: string }   // options for selects, lists, comboboxes
+```
+
+### Eventer
+
+```ts
+import { Eventer } from '@electral-io/webspa';
+
+const changed = new Eventer<string, void>();
+const ac = new AbortController();
+changed.register((data) => console.log(data), ac.signal);   // the signal unregisters automatically
+await changed.raise('hello');
+ac.abort();   // or changed.unregister(listener)
+```
+
+### Observable properties
+
+```ts
+class Model extends Observable { @Observe() status: string; }
+model.onPropChanged.register(({ name, oldValue, newValue }) => { /* ... */ });
+```
+
+`BaseElement` is observable too.
+
+### System & DateHelper
+
+```ts
+System.isNullOrUndefined(v); System.isEmpty(v); System.isString(v); System.toNumber('5');
+await System.wait(500); System.downloadBlob(blob, 'file.xlsx');
+DateHelper.isoStrToDate(str); DateHelper.dateToIsoStr(date); DateHelper.formatIsoStr(str);
+```
+
+### List & IndexedList
+
+```ts
+const list = new List<Item>(a, b);          // observable array: add, remove, changeEvent...
+const items = new IndexedList<Item>(a, b);  // observable list with ids: source for ListComponent / TreeView
+items.find(x => x.key == 'k');
+```
+
+---
+
+## Components
+
+All components are Custom Elements. Create them with `new` and append them to the DOM.
+
+### Writing your own component
+
+```ts
+@Component({ elementName: 'app-order-card' })   // unique, must contain a dash
+export class OrderCard extends BaseElement {
+    constructor() { super(); this.appendChild(ELF.span('...')); }
+    protected onConnected(isFirst?: boolean) { if (!isFirst) return; /* load */ }
+}
+```
+
+`BaseElement` provides `getDisposedSignal()` (aborted on disconnect), `setBusy(true|false)`, `visible`, `bag`, `onPropChanged` and `canClose()`.
+
+### ELF (element factory)
+
+```ts
+ELF.div('my-class', child1, 'text');
+ELF.span('text', 'cls'); ELF.label('Name'); ELF.h(3, 'Title'); ELF.input('text', '', 'placeholder');
+ELF.button('Save', 'Save changes', 'primary', IconClass.save, async (ev, btn) => { await save(); });
+ELF.Buttons.delete(() => remove());
+ELF.build({ tag: 'div', attrs: { className: 'card' }, children: [ /* ... */ ] });
+ELF.showHideSpinnerAt(elm, true);
+```
+
+### Inputs
+
+```ts
+const combo = new ComboBox([{ key: 1, title: 'A' }, { key: 2, title: 'B' }]);   // or an async loader
+const child = new ComboBox({ parents: [combo], itemLoader: async (parentValues) => loadChildren(parentValues[0]) });
+combo.value = 1;
+combo.onValueChanged.register(v => console.log(v));
+
+new MultiComboBox(items);                         // value: LookupValue[]
+new CheckList({ items });                         // value: LookupValue[]
+new ButtonRadio({ source: items });               // value: LookupValue
+new TagInput('text');                             // value: string[]
+new DateRangeComponent({ inputType: 'date' });    // value: { startDate, endDate }
+new AutoComplete({ loader: async (text) => lookups });
+new TreeView(new IndexedList<ITreeItem>(...nodes), { selection: { mode: 'multi' } });
+```
+
+### Form
+
+```ts
+const form = new Form<Customer>({
+    columns: 2,
+    inputs: [
+        { key: 'name', title: 'Name', input: 'text', rules: [new RequiredRule()] },
+        FormUtils.generateFormInputForCombobox('typeId', 'Type', typeLookups),
+        { key: 'active', title: 'Active', input: 'switch' },
+    ],
+});
+form.setData(customer);
+if (form.check()) { const data = form.getData(); }
+```
+
+### DataTable
+
+```ts
+const cc = new DataTableColCreator<Order>();
+const table = new DataTable<Order>({
+    uniqueKey: 'orders',
+    title: 'Orders',
+    columns: {
+        idField: 'id',
+        modelColumns: {
+            id: cc.createBasicCol('id', 'ID'),
+            createdAt: cc.createDateTimeIsoStrCol('createdAt', 'Date'),
+            status: cc.createLookupCol('status', 'Status', statusLookups),
+        },
+    },
+    dataLoader: async () => api.listOrders(),        // returns OpResult<Order[]>
+    pagination: { size: 20 },
+    actions: { export: { xls: true, pdf: true } },
+    segments: { items: [{ key: 'open', title: 'Open', filters: [{ field: 'status', type: '=', value: 1 }] }, { key: 'all', title: 'All' }] },
+});
+```
+
+Use `DtRenderers` for cells (`cc.createCol('status', 'Status', DtRenderers.status({ '1': { tone: 'info', text: 'Open' } }))`). Table actions with `bulk: true` appear only while rows are selected. Column layout and row density are stored per user.
+
+### Notifications & dialogs
+
+```ts
+Notify.Success('Saved');                 // also Error, Warning, Info: (title, message?)
+const w = Notify.Wait('Working...'); w.hide();
+
+await MessageBox.Info('Done.');          // also Error, Success, Warning, ShowOk
+const yes = await MessageBox.Yesno('Delete this record?');
+const name = await MessageBox.InputText('Enter a name');
+const res = await MessageBox.ShowAsync({ title: 'Edit', content: form, buttons: 'OkCancel' });   // res?.ok
+await DialogWindow.ShowAsync('Title', contentElement);
+```
+
+### Layout & containers
+
+```ts
+new Flex({ direction: 'row', gap: 'var(--spacing)' }, a, b);
+new Grid({ cols: 'auto 1fr' }, label, input);
+new GroupBox('Details', child1, child2);
+const tabs = new TabContainer();
+tabs.addTab({ name: 't1', header: 'Overview', content: elm }, true);
+tabs.activateTab('t1');
+new DrawerContainer({ main: mainElm, left: { title: 'Filters', content: filtersElm, openMode: 'click' } });
+new Accordion({ header: 'More', content: elm });
+```
+
+### Component summary
+
+| Component | Description |
+|---|---|
+| `ComboBox`, `MultiComboBox`, `AutoComplete`, `CheckList`, `ButtonRadio`, `TagInput` | Inputs (`value`, `onValueChanged`, `readOnly`) |
+| `DateRangeComponent`, `DropDownDateRange` | Date range pickers |
+| `TreeView`, `DropdownTree` | Hierarchical selection |
+| `Form` | Config-driven form with validation |
+| `DataTable` | Tabulator table with search, filters, CRUD and Excel/PDF export |
+| `ListComponent`, `GrouppedListComponent` | Lists over an `IndexedList` |
+| `Flex`, `Grid`, `GroupBox`, `Card`, `Accordion`, `Empty` | Layout |
+| `TabContainer`, `DrawerContainer` | Containers |
+| `Toolbar`, `ButtonList`, `DropdownButton`, `Menu`, `OptionsMenu`, `ContextMenu`, `RadialMenu`, `RibbonMenu` | Buttons & menus |
+| `Notify`, `MessageBox`, `DialogWindow` | Feedback (static APIs) |
+| `MessageDisplay`, `Spinner`, `IndeterminateProgress`, `Skeleton` | Status display |
+| `ConditionalElement` | Swaps content on an observable property |
+| `SummaryCard`, `ProgramCard` | KPI card / progress card (in `.summary-card-row` / `.program-card-grid`) |
+| `ListPanel`, `MasterDetailLayout` | Left list with segments + search; master / detail / aside layout |
+| `FormPanel` | Side-panel form container: numbered sections, sticky footer, missing-field summary |
+| `DtRenderers` | DataTable cell formatters: `pill`, `status`, `priority`, `tag`, `remainingDays`, `toggle`, `actions` |
+
+---
+
+## Framework & Dependency Injection
+
+### Services
+
+```ts
+@Service({ type: ServiceTypes.Singleton })   // Singleton | Scoped (default) | Transient
+export class ApiService { async getUsers(): AsyncOpResult<User[]> { /* ... */ } }
+
+@Service()
+export class OrderService {
+    @Inject() private api: ApiService;        // lazy, resolved by type on first access
+}
+```
+
+| Lifetime | Behavior |
+|---|---|
+| `Singleton` | One instance for the app lifetime |
+| `Scoped` | Recreated when the user scope changes (login / logout) |
+| `Transient` | New instance on every resolution |
+
+Built-in services you can inject: `Application`, `EventService`, `CommandService`, `AuthService`, `StoreService`, `NavigationService`, `DepResService`, `FormService`.
+
+### Panels
+
+```ts
+@Inject() application: Application;
+
+await this.application.openPanelAsnc({
+    name: 'orders', header: 'Orders', content: new OrderList(), closable: true, draggable: true,
+}, PanelPos.Right);   // Center | Left | Right | Bottom | Window
+
+await this.application.closePanelAsync('orders');
+```
+
+### Pages
+
+```ts
+@Component({ elementName: 'page-dashboard', classes: ['page'] })
+@Page({ key: 'dashboard', title: 'Dashboard', iconClass: IconClass.layers, auth: 'dashboard-view' })
+export class DashboardPage extends BasePage {
+    OnShow(): void { }
+    OnHide(): void { }
+}
+```
+
+### Commands (ribbon)
+
+```ts
+@Command({
+    type: CommandTypes.Command,                  // Command | Tool | Select | Custom
+    container: FrameworkCommandTargets.Ribbon,   // 'ribbon' | 'user-menu' | custom container
+    group: 'mg-general-file',                    // a group key from ApplicationProperties.ribbon
+    key: 'cmd-save',
+    title: 'Save',
+    iconClass: IconClass.save,
+    order: 1,
+    auth: 'save_record',                         // optional permission key
+})
+export class SaveCommand extends BaseCommand {
+    start(childKey?: string, param?: any): void { /* ... */ }
+}
+```
+
+Tools (`CommandTypes.Tool`) stay active until another tool starts. They implement `cancel(): boolean`, or extend `BaseDisposableTool`. Start any command from code with `commandService.startCommand(key, childKey, param)`.
+
+### Events
+
+```ts
+@Inject() eventService: EventService;
+this.eventService.listen('orders-changed', (data) => { /* ... */ }, this.getDisposedSignal());
+await this.eventService.raise('orders-changed', data);
+```
+
+Framework events are in `SystemEvents` (`ApplicationStart`, `UserLogin`, `UserLogout`, `PageNavigated`, `ThemeDarkChanged`, ...).
+
+### Startup & periodic jobs
+
+```ts
+@StartupJob('load-config', { type: StartupJobTypes.PreLoad, title: 'Config', required: true })
+class LoadConfigJob implements IAppStartupJob {
+    name = 'load-config';
+    async run(): Promise<boolean> { /* ... */ return true; }
+}
+
+@PeriodicJob({ key: 'refresh', tick: 240 })   // 1 tick = 250 ms, so 240 = 1 minute
+class RefreshJob implements IPeriodicJob { name = 'refresh'; async run() { return true; } }
+```
+
+### Localization
+
+```ts
+export const AppDictionary = { orders: { tr: 'Siparişler', en: 'Orders' } };
+registerDictionary(AppDictionary);
+export const txtApp = (key: keyof typeof AppDictionary, ...p: string[]) => txtSpa(key as any, ...p);
+```
+
+---
+
+## Application Startup
+
+```ts
+import './pages/**/*';      // modules must be imported so their decorators register
+import './commands/**/*';
+
+class MainStartup extends AppStartup {
+    onReady(): void { /* the shell is ready */ }
+}
+
+const props: ApplicationProperties = {
+    hostElement: document.body,
+    title: 'My App',
+    subtitle: 'v1.0',
+    logoUrl: '',
+    apiEndPoint: 'https://api.example.com/',
+    defaultPage: FrameworkPages.App,
+    adminPageDisabled: true,
+    languages: ['tr', 'en'],
+    auth: {
+        type: 'Local',
+        autoLogin: true,
+        loginInfoUrl: '',
+        createLoginComponent: () => new SimpleLoginComponent({
+            loginButtonText: 'Login', userPlaceholder: 'User', passPlaceholder: 'Password',
+            loginAction: async ({ ukey, pass }) => api.login(ukey, pass),   // returns OpResult<ILoginInfo>
+        }),
+    },
+    ribbon: {
+        defaultTool: 'pan',
+        tabs: [{ key: 'tab-general', title: 'General', order: 1,
+                 items: [{ key: 'mg-general-file', title: 'File', order: 1 }] }],
+    },
+    themes: [{ key: 'teal', title: 'Teal', color1: 'var(--teal-600)', color2: 'var(--cyan-600)' }],
+};
+
+new MainStartup().run(props);
+```
+
+---
+
+## GIS (map apps)
+
+The GIS layer (`src/gis`) is exported from the same package root. It is built on OpenLayers 10 and adds a map panel (map + legend + layer tree), built-in ribbon map tools (pan, basemaps, extent history, full extent, fullscreen, go to, print, measure line/area), layer types, identify/popups, selection and search.
+
+```ts
+import { GisAppService, GisEvents, LayerDefinitionTypes, BaseMapTypes, MapManager, LayerManager } from '@electral-io/webspa';
+```
+
+Map apps need `ol` (10.x) in their own dependencies, plus `proj4`, `@terraformer/arcgis`, `geojson` and `coordinate-parser` at the versions in this package's `package.json`.
+
+**Coordinates are lon/lat (EPSG:4326)** everywhere: the library calls `useGeographic()`. Centers are `[lon, lat]`, extents `[minLon, minLat, maxLon, maxLat]`.
+
+### Map app setup
+
+`GisAppService` is abstract: subclass it as a service and call `startMapComponents` once the shell is ready.
+
+```ts
+@Service({ type: ServiceTypes.Scoped })
+export class MapAppService extends GisAppService { }
+
+class MainStartup extends AppStartup {
+    @Inject() mapApp: MapAppService;
+    onReady(): void {
+        this.mapApp.startMapComponents({
+            baseMap: BaseMapTypes.GoogleSatellite,   // GoogleRoad | GoogleSatellite | EsriGrayLight | EsriGrayDark | EsriTopo | Osm | Solid
+            defaultLocation: { center: [32.85, 39.93], zoom: 12 },
+            layerLoader: async () => ({ success: true, data: layerDefinitions }),   // LayerDefinition[]
+            customLayerFactory: new AppLayerFactory(),   // handles LayerDefinitionTypes.Custom
+            searchSources: [new MySearch()],
+            ExternalApiSettings: { proxyUrl: '/proxy', google: { apikey: '...', useProxy: true } },
+        });
+    }
+}
+```
+
+It opens a non-closable center panel `panel-map-main` (map + a left drawer with Legend and Layers tabs) and starts the ribbon's `defaultTool` when `GisEvents.MapReady` fires. The built-in tools register into the ribbon groups `mg-general-map`, `mg-general-measure` and `mg-general-query`: include these keys in `ApplicationProperties.ribbon` and set `defaultTool: 'pan'`. Permission keys used by built-ins: `Map-Print`, `Google-StreetView`, `Google-Geocode`.
+
+### Layers
+
+Layers are described with `LayerDefinition` objects (`type`, `key`, `order`, `title`, `visible`, `minZoom?`, `maxZoom?`, `props`):
+
+```ts
+const layerDefinitions: LayerDefinition[] = [
+  { type: LayerDefinitionTypes.EsriMapService, key: 'lyr-usa', order: 1, title: 'USA', visible: true,
+    props: { url: 'https://.../MapServer', tiled: false, useProxy: false } },
+  { type: LayerDefinitionTypes.WMS, key: 'lyr-poles', order: 2, title: 'Poles', visible: true, minZoom: 14,
+    props: { url: 'https://geo/geoserver/ws/wms', layers: 'ws:poles', imagetype: 'image/png', tiled: true,
+             useProxy: false, wfsEnabled: false, shapefield: 'geom' } },
+  { type: LayerDefinitionTypes.Custom, key: 'lyr-vehicles', order: 3, title: 'Vehicles', visible: true,
+    props: { factoryKey: 'vehicles', customProps: { refreshSec: 10 } } },
+];
+```
+
+ArcGIS MapServer and WMS have built-in factories. Everything else (XYZ tiles, MVT, groups, client vector layers) goes through your single custom factory, an `ILayerFactory` whose `createAsync(ld)` returns the layer. Base classes for custom layers: `MapLayerBase`, `WmsLayer` / `WmsLayerBase`, `MvtLayerBase`, `TileXyzLayer`, `GroupLayerBase`. Add or remove layers at runtime with `LayerManager` (`addLayer`, `removeLayer`, `findLayer`).
+
+### Managers and events
+
+Inject `MapManager` (`map`, `view`, `goto`, `gotoFullExtent`, `flashGeom`, `selectAreaFromMap`, ...) and `LayerManager`. Non-map code can navigate through events:
+
+```ts
+eventService.raise(GisEvents.MapGotoExtentRequest, { extent: [minLon, minLat, maxLon, maxLat] });
+eventService.raise(GisEvents.BasemapChange, BaseMapTypes.Osm);
+```
+
+Other events: `MapReady`, `MapFirstRenderComplete`, `MapIdentifyRequest`, `MapSelectionChanged`, `MapIdleRefresh`, `MapTimeChanged`, `RemoveLayer`.
+
+### Map tools and selection
+
+Map tools are ordinary commands with `CommandTypes.Tool` in the `GisCommandContainers.ribbon` container; right-click menu commands use `GisCommandContainers.mapCtx` with `canExecuteFor`. To select features, start the default `pan` tool with an `IMapSelectionContext`:
+
+```ts
+const ctx: IMapSelectionContext = {
+    mode: 'polygon',                      // 'single' | 'freehand' | 'polygon'
+    makeSelected: true,
+    contextMenuContainer: GisCommandContainers.mapCtx,
+    layerFilter: (lyr) => getLayerProps(lyr)?.mapLayer?.id == 'lyr-poles',
+    completeWork: (items, geom) => { /* items: SelectedMapItem[] */ },
+};
+commandService.startCommand('pan', null, ctx);
+```
+
+For an area only, use `mapManager.selectAreaFromMap('polygon', maxKm2, signal)`.
+
+### Search and proxy
+
+Pass `ILocalSearchSource` / `IRemoteSearchSource` instances in `searchSources`; `GoogleGeocodingSearchSource` is built in (needs `google.apikey` and the `Google-Geocode` permission). External requests that need a proxy go through `GET {proxyUrl}?<encoded url>` (`ExternalApiSettings.proxyUrl`, default `{apiEndPoint}/proxy`). `.proxyrc.cjs` is the dev-server equivalent.
+
+---
+
+## Development
+
+```bash
+npm install
+npm run debug        # core demo, http://localhost:5544
+npm run debug-gis    # map demo, http://localhost:5545
+npm run build        # dist/index.js, dist/index.d.ts, dist/index.css (core + GIS/OpenLayers styles)
+npm run css-data     # regenerate static/web-spa-css-custom-data.json after changing src/style/theme/*.less
+npm run doc          # typedoc (doc-md for Markdown output)
+```
+
+Layout: `src/core`, `src/elements`, `src/framework`, `src/style` (core), `src/gis` (GIS), `src/spa.ts` (core barrel) and `src/index.ts` (public entry: `export * from './spa'` and `'./gis'`).
+
+Google map / Street View in `debug-gis` needs an API key. Put it in a git-ignored `.env` file at the repo root (read by `.proxyrc.cjs`, which appends it server side):
+
+```
+GOOGLE_MAPS_API_KEY=your-key
+```
+
+## Release
+
+Publishing is done by GitHub Actions (`.github/workflows/publish.yml`) when a GitHub Release is published, using npm Trusted Publishing (OIDC), so no npm token is stored. To release:
+
+1. Bump `version` in `package.json`.
+2. Merge to the default branch.
+3. Create a GitHub Release (tag `vX.Y.Z`) in github.com/electral-io/webspa.
+
+---
+
+## Claude Code skill
+
+This repo ships a Claude Code plugin with the `web-spa` skill (`claude-plugin/skills/web-spa/`). The skill teaches Claude these APIs (core and GIS) and the CSS token rules. Install it once:
+
+```
+/plugin marketplace add electral-io/webspa
+/plugin install web-spa@electral-io
+```
+
+Get updates with `/plugin marketplace update electral-io`. Projects can preinstall it for everyone through `extraKnownMarketplaces` and `enabledPlugins` in their `.claude/settings.json`.
+
+---
+
+## License
+
+ISC © Electral