tsgrid-ui 2.7.1 → 2.10.0

package/CHANGELOG.md

@@ -2,6 +2,223 @@
 
 All notable changes to **TsGrid UI** will be documented in this file.
 
+## v2.10.0 — 2026-05-15
+
+### Tree-shake-friendly lazy singletons
+
+`TsPopup`, `TsTooltip`, `TsMenu`, `TsColor`, and `TsDate` now defer their underlying class
+construction until first use via a Proxy-based lazy-init pattern. Consumers that import
+`tsgrid-ui/popup` or `tsgrid-ui/tooltip` but do NOT call any method get a smaller bundle —
+bundlers respecting `sideEffects` can now eliminate the constructor bodies.
+
+- `package.json#sideEffects[]` no longer lists `./dist/popup.es6.js` or `./dist/tooltip.es6.js`.
+- Public API unchanged: same imports, same method calls, same `instanceof`, same `vi.spyOn` behavior.
+- Internal: new `src/lazy-singleton.ts` helper, named export `__test_internals` on `tspopup.ts`
+  and `tstooltip.ts` for construction-count assertions.
+
+Not changed in this release (deferred to future cycles):
+- `TsUtils` stays eager — its constructor reads `navigator` and `localStorage` (real side-effects
+  regardless of timing).
+- SSR safety remains future work.
+- `Tooltip.observeRemove = new MutationObserver(...)` static field is unchanged.
+
+### Implementation
+
+- `src/lazy-singleton.ts` (NEW): `lazySingleton<T>(factory, protoRef): T` — Proxy helper with
+  `get`, `set`, `has`, `ownKeys`, `getOwnPropertyDescriptor`, `defineProperty`, `getPrototypeOf`
+  traps. Factory invoked at most once; `getPrototypeOf` returns `protoRef.prototype` without
+  materializing to preserve `instanceof` semantics without triggering construction.
+- `src/tspopup.ts`: `TsPopup = lazySingleton<TsDialog>(...)` replaces `new TsDialog()`.
+- `src/tstooltip.ts`: four `lazySingleton(...)` calls replace `new Tooltip()` / `new MenuTooltip()`
+  / `new ColorTooltip()` / `new DateTooltip()`.
+
+### Tests
+
+- `test/unit/singleton-lazy-init.test.ts` (NEW): T-LAZY-1..8 covering deferred construction,
+  exactly-once guarantee, singleton identity, `vi.spyOn` forwarding, `TsUtils.lang` init-chain
+  safety, and `instanceof` invariant.
+- `test/unit/package-json.test.ts`: updated to assert 7-entry `sideEffects[]` and version 2.10.0.
+- `test/unit/bundle-snapshot.test.ts`: added R-SLI-DESIGN-3 ctor-marker assertions for
+  `popup.es6.js` and `tooltip.es6.js` stubs.
+
+### BC
+
+- Public API surface: **purely additive**. All existing imports and call sites work unchanged.
+- SEMVER MINOR per SemVer §7. No breaking changes.
+
+## v2.9.0 — 2026-05-15
+
+### Added
+
+- **`TsToolbar.toggle(...args): any[]` — new public API** (`src/tstoolbar.ts:481`): flips the `checked` state of one or more items without firing events or opening overlays. Complements `check()` / `uncheck()` / `click()`:
+  - `button` / `check` / `html` / `spacer` / `break`: flip `it.checked`.
+  - `drop` / `menu` / `menu-radio` / `menu-check` / `color` / `text-color`: if currently checked, closes the toolbar's `-drop` overlay via `TsTooltip.hide` before flipping (mirrors `uncheck()` overlay-close path). Never opens overlays.
+  - `radio`: `console.warn` + skip. Use `check()` / `uncheck()` for radios.
+  - `group`: recurses into `it.items`; the container itself is never in the effected list.
+  - `sub-id` with `:` notation and missing ids: silently skipped.
+  - Returns the array of ids whose state actually flipped (never `undefined`).
+  - State-only — does NOT fire `onClick` or `onChange`.
+
+### Fixed (toolbar polish-lifecycle)
+
+- `setCount` no longer recurses into non-count item types — guarded at function entry (`7d721185`).
+- `destroy()` now closes pending overlays before unmount, preventing detached tooltip refs (`01752f36`).
+- `menu-check` items now seed `selected` from `it.items` function-form returns at insert time (`712a1bac`).
+
+### Fixed (toolbar polish-api)
+
+- `get(id, true)` and `remove()` now compute the correct sub-item index inside group containers (`8a522974`, Smell 6).
+
+### Refactor (toolbar polish-api)
+
+- Removed unreachable `item.type==null` guard in toolbar render path (`50c8f2ea`, Smell 2).
+
+### Style (toolbar polish-api)
+
+- Single display value emitted for hidden-group sub-items (`2418f929`, Smell 4).
+- Intentional switch fall-through explicitly annotated (`577bd566`, Smell 3).
+
+### Build / Dist
+
+- Removed orphan chunks from analyze build (`459b8202`, closes WARNING-V1).
+- Rebuilt CJS dist with v2.8.1 banner (`48960492`, closes WARNING-V2).
+- Rebuilt `dist/` after polish-api merge — restored coherence (`35fd76ba`, closes WARNING-V4).
+
+### BC
+
+- Public API surface: **purely additive**. `TsToolbar.toggle()` is new; all existing methods unchanged.
+- SEMVER MINOR (new public API on `TsToolbar`).
+
+### Internal
+
+- Verify-pass for v2.8.1 (`2bcb55a3`) was completed on the `feature/v2.8.1-chunk-splitting-side-effects` branch before polish-lifecycle (3 fixes), polish-api Smells (2/3/4/6), and `toggle()` API landed on master. v2.9.0 packages those post-verify additions as a minor release.
+
+## v2.8.1 — 2026-05-15
+
+### Added
+
+#### Bundle
+
+- **`sideEffects` per-file map** — `package.json` now declares an explicit 9-entry
+  `sideEffects` array, enabling webpack and rollup to tree-shake unused subpaths:
+  - Side-effectful (must load): `tsgrid-ui.css`, `tsgrid-ui.min.css`,
+    `utils.es6.js`, `popup.es6.js`, `tooltip.es6.js`, `tsgrid-ui.es6.js`,
+    `tsgrid-ui.es6.min.js`, `tsgrid-ui.js`, `tsgrid-ui.min.js`.
+  - Implicitly pure (may tree-shake): `locale.es6.js`, `base.es6.js`,
+    `tabs.es6.js`, `toolbar.es6.js`, `sidebar.es6.js`, `field.es6.js`,
+    `layout.es6.js`, `form.es6.js`, and all `dist/chunks/*.js`.
+  - **IMPORTANT**: esbuild (and therefore vite, tsup) does **NOT** honor
+    `package.json sideEffects`. Only webpack and rollup benefit from this field.
+    esbuild's own tree-shaking is based solely on static analysis of ESM imports.
+
+- **ESM shared chunks under `dist/chunks/`** — `splitting: true` is now active in the
+  ESM non-min block (`tsup.config.ts` block 1). esbuild extracts shared code into
+  `dist/chunks/chunk-<8CHAR>.js` files automatically. With 12 entry points, 10 chunks
+  are produced. Consumers importing multiple subpaths load shared code once.
+
+- **Multi-subpath byte savings** (webpack/rollup consumers):
+  - SC-A (`./popup` + `./form`): **19.8% reduction** (627,883 B → 503,563 B effective)
+  - SC-B (`./popup` + `./tooltip` + `./tabs`): **54.9% reduction** (672,606 B → 303,119 B)
+  - SC-C (`./locale` only): +123 B overhead (+3.2%, well within ≤1 KB canary threshold)
+  - SC-D (monolith `.`): +2,348 B overhead (+0.25%, within ±2% AC10 allowance)
+  - Full scenario table: `reports/bundle/v2.8.1-splitting-savings.md`
+
+- **Cycle 5 forward reference** — `dist/utils.es6.js`, `dist/popup.es6.js`, and
+  `dist/tooltip.es6.js` remain in the `sideEffects` array because their constructors
+  run module-level side effects at import time (global singleton registration).
+  Cycle 5 (singleton lazy-init refactor) will remove these from the array, unlocking
+  additional savings for esbuild/vite consumers that currently cannot benefit.
+
+- **`dist/chunks/` must ship with the package** — consumers installing tsgrid-ui from
+  npm must ensure `dist/chunks/*.js` files are present. The `package.json files` array
+  already covers `dist/` recursively; no additional configuration needed.
+
+### BC
+
+- Public API surface: **purely additive**. All existing `import` paths are unchanged.
+  `dist/chunks/` is a new subdirectory but is an implementation detail — not a public API.
+- SEMVER PATCH. No breaking changes.
+
+---
+
+### Fixed (build)
+- `scripts/wrap-legacy.mjs`: `buildHeader()` is now deterministic — per-build
+  `new Date().toLocaleString('en-us')` timestamp removed. Version string is now
+  read dynamically from `package.json` via `readFile + JSON.parse` (was stale
+  hardcoded `1.0.x (nightly)`). CJS dist artifacts (`dist/tsgrid-ui.js`,
+  `dist/tsgrid-ui.min.js`) are now bit-identical across consecutive rebuilds
+  on unchanged source.
+- Anti-regression: new Vitest unit test at `test/unit/wrap-legacy.test.ts`
+  guards against reintroduction of `new Date(`, `Date.now(`, `Math.random(`
+  in the post-build script.
+
+### Notes (build)
+- SEMVER: chore — no version bump.
+- Supersedes the CJS-SHA Option-B caveat from the bundle-baseline-instrumentation
+  cycle (spec #960 INV-BBI-1). Future cycles MAY assume strict CJS-SHA equality
+  across all 5 dist artifacts.
+
+### Added (tooling)
+- `pnpm bundle:analyze` — generate esbuild metafile + per-module advisory summary (`reports/bundle/latest.md`, gitignored).
+- `pnpm bundle:snapshot -- --version=vX.Y.Z` — write committed baseline JSON to `reports/bundle/<version>-baseline.json`.
+- `tsup.config.analyze.ts` — analyze-only tsup config (single ESM-non-min block + `metafile: true`); structurally isolated from `tsup.config.ts` (INV-ANALYZE-ISOLATION).
+- `reports/bundle/v2.7.1-baseline.json` — v2.7.1 ESM-non-min per-module byte composition. This artifact unlocks Phase 2 (subpath exports) acceptance testing (INV-CYCLE-1-HARD-GATE).
+- `reports/bundle/README.md` — schema + scope documentation.
+
+### Internal
+- Zero new devDependencies. Zero changes to `src/`. Zero changes to `dist/*.js` on production builds (byte-identical, verified via `shasum` gate).
+- SEMVER: chore / no version bump. Next version bump (v2.8.0) reserved for Phase 2 (subpath exports).
+
+## v2.8.0 — 2026-05-14
+
+### Added
+
+- **Subpath exports** — 11 new `package.json` export entries enable tree-shakable imports
+  (amendment #983: `./grid` deferred to Phase 3 pending `splitting:true` code-split):
+  - `tsgrid-ui/locale` → `TsLocale` (~3,843 B, 99.6% smaller than barrel)
+  - `tsgrid-ui/base` → `TsBase`, `TsEvent`, `toSafeEvent` (~32,135 B, 96.6% smaller)
+  - `tsgrid-ui/utils` → `TsUi`, `TsUtils`, `query` (~127,812 B, 86.5% smaller)
+  - `tsgrid-ui/popup` → `TsPopup`, `TsAlert`, `TsConfirm`, `TsPrompt`, `TsDialog` (~159,775 B, 83.1% smaller)
+  - `tsgrid-ui/tooltip` → `TsTooltip`, `TsMenu`, `TsColor`, `TsDate`, `Tooltip` (~244,488 B, 74.1% smaller)
+  - `tsgrid-ui/tabs` → `TsTabs` (~268,343 B, 71.6% smaller)
+  - `tsgrid-ui/toolbar` → `TsToolbar` (~288,428 B, 69.5% smaller)
+  - `tsgrid-ui/sidebar` → `TsSidebar` (~306,229 B, 67.6% smaller)
+  - `tsgrid-ui/field` → `TsField` (~312,704 B, 66.9% smaller)
+  - `tsgrid-ui/layout` → `TsLayout` (~354,172 B, 62.5% smaller)
+  - `tsgrid-ui/form` → `TsForm` (~468,108 B, 50.5% smaller)
+- **`./package.json` export** — enables tooling that reads package metadata at runtime.
+- **`reports/bundle/v2.8.0-baseline.json`** — schemaVersion 2; per-subpath empirical byte
+  measurements. Phase 2 gate for the v3.0 tree-shakable roadmap.
+- Grid users continue using the barrel import (`tsgrid-ui`); `./grid` subpath export deferred
+  to Phase 3 once `splitting:true` reduces transitive duplication.
+
+### Bundle
+
+- Monolith `tsgrid-ui` entry unchanged at 945,470 bytes (byte-identical to v2.7.1).
+- Subpath bundles emitted with `splitting: false`; shared modules re-emitted per subpath.
+  Most modern bundlers deduplicate transparently (esbuild, Rollup, Vite, webpack 5+, Parcel 2+).
+- `splitting: true` shared-chunk optimization planned for v2.9 / Phase 3.
+- Dist artifact count: 7 → 29 files (+11 ESM subpath bundles + 11 `.d.ts` files).
+
+### BC
+
+- Public API surface: **purely additive**. The `"."` barrel entry is byte-identical to v2.7.1.
+- `dist/tsgrid-ui.es6.js` SHA: byte-identical to v2.7.1 (INV-SX-6 PASS).
+- `src/index.ts` barrel: byte-identical to v2.7.1 (INV-7 PASS).
+- No `require:` condition on subpaths — CJS consumers continue using `'tsgrid-ui'` barrel.
+  CJS subpaths planned for Phase 4 (requires `wrap-legacy.mjs` per-symbol refactoring).
+- No barrel deprecation: `'tsgrid-ui'` barrel is fully supported with zero deprecation markers.
+- SEMVER MINOR per SemVer §7. No breaking changes.
+
+### Tests
+
+- `test/unit/subpath-exports.test.ts` (NEW) — 3 groups: exports shape, dist existence,
+  bundle floor. All 3 groups GREEN from Phase 6 onward.
+- `test/consumer-smoke.ts` — extended with 11 named-import probes + 11 type-only probes.
+- Total Vitest tests: **352/352 GREEN** (v2.7.1 baseline: 301/301 — +13 new assertions
+  plus expanded parametric tests via `it.each`).
+- `tsup.config.analyze.ts`: UNCHANGED (INV-ANALYZE-ISOLATION PASS).
+
 ## v2.7.1 — 2026-05-14
 
 ### Fixed

package/dist/base.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Part of TsUi 2.0 library
+ *  - Dependencies: TsUtils
+ *  - on/off/trigger methods id not showing in help
+ *  - refactored with event object
+ *
+ * Chanes in 2.0.+
+ * - added unmount that cleans up the box
+ *
+ */
+/**
+ * Payload object passed to handlers registered via `.on(eventName, handler)`.
+ *
+ * IMPORTANT — circular references:
+ *   `event.owner` points back to the widget that triggered the event, and that
+ *   widget keeps `activeEvents: TsEvent[]` referencing this same payload.
+ *   Calling `JSON.stringify(event)` will throw "Converting circular structure
+ *   to JSON". Use `toSafeEvent(event)` from `tsgrid-ui` to extract a
+ *   serializable subset before storing in reactive state (Angular signals,
+ *   React state, Pinia/Redux stores, etc.).
+ *
+ * Note: the per-class declarations like `onSelect: (event: CustomEvent) => void`
+ * in TsGrid/TsForm/etc. are historical noise — the runtime always passes a
+ * `TsEventPayload`, never a DOM `CustomEvent`. This will be corrected in v2.0.
+ */
+interface TsEventPayload<TDetail = unknown> {
+    type: string | null;
+    phase: 'before' | 'after' | string;
+    detail: TDetail & TsEventData;
+    target: unknown;
+    object: unknown;
+    isStopped: boolean;
+    isCancelled: boolean;
+    /** Reference to the widget that triggered this event. CIRCULAR — do not serialize. */
+    owner: unknown;
+}
+interface TsEventData {
+    type?: string | null;
+    target?: unknown;
+    phase?: string;
+    object?: unknown;
+    [key: string]: unknown;
+}
+interface TsEventListener {
+    name: string;
+    edata: {
+        type: string | null;
+        execute: string;
+        onComplete: null;
+        scope?: string;
+        handler?: unknown;
+        [key: string]: unknown;
+    };
+    handler: Function;
+}
+declare class TsEvent {
+    type: string | null;
+    detail: TsEventData;
+    owner: TsBase;
+    target: unknown;
+    phase: string;
+    object: unknown;
+    execute: null;
+    isStopped: boolean;
+    isCancelled: boolean;
+    onComplete: ((edata: TsEvent) => void) | null;
+    listeners: Array<(edata: TsEvent) => void>;
+    complete: Promise<TsEvent>;
+    _resolve: (value: TsEvent) => void;
+    _reject: (reason?: unknown) => void;
+    constructor(owner: TsBase, edata: TsEventData);
+    finish(detail?: Partial<TsEventData>): void;
+    done(func: (edata: TsEvent) => void): void;
+    preventDefault(): void;
+    stopPropagation(): void;
+}
+/**
+ * Extract a JSON-serializable subset of a TsEvent payload, dropping the
+ * circular `owner` and `complete` references. Use before storing in
+ * Angular signals, React state, Pinia/Redux stores, or any DevTools that
+ * snapshots state via JSON.
+ *
+ * @example
+ *   grid.on('select', (event) => {
+ *     this.lastSelection.set(toSafeEvent(event))
+ *   })
+ */
+declare function toSafeEvent<TDetail = unknown>(event: unknown): {
+    type: string | null;
+    phase: string;
+    detail: TDetail & TsEventData;
+    isStopped: boolean;
+    isCancelled: boolean;
+};
+declare class TsBase {
+    activeEvents: TsEvent[];
+    listeners: TsEventListener[];
+    debug: boolean;
+    name?: string;
+    box?: HTMLElement | null;
+    [key: string]: unknown;
+    /**
+     * Initializes base object for TsUi, registers it with TsUi object
+     *
+     * @param {string} name  - name of the object
+     * @returns
+     */
+    constructor(name?: string);
+    /**
+     * Adds event listener, supports event phase and event scoping
+     *
+     * @param {*} edata - an object or string, if string "eventName:phase.scope"
+     * @param {*} handler
+     * @returns itself
+     */
+    on(events: string | TsEventData | Array<string | TsEventData>, handler: Function): this;
+    /**
+     * Removes event listener, supports event phase and event scoping
+     *
+     * @param {*} edata - an object or string, if string "eventName:phase.scope"
+     * @param {*} handler
+     * @returns itself
+     */
+    off(events: string | TsEventData | Array<string | TsEventData>, handler?: Function): this;
+    /**
+     * Triggers even listeners for a specific event, loops through this.listeners
+     *
+     * @param {Object} edata - Object
+     * @returns modified edata
+     *
+     * NOTE: `edata` is typed as `any` here intentionally. The method mutates the argument
+     * from TsEventData into a TsEvent mid-execution. Runtime type mutation is inherent
+     * to the event dispatch pattern. Phase 6 strict tighten will revisit this.
+     */
+    trigger(eventName: string | TsEventData | TsEvent, edataIn?: TsEventData): TsEvent;
+    /**
+     * This method renders component into the box. It is overwritten in descendents and in this base
+     * component it is empty.
+     */
+    render(_box?: HTMLElement | string | null): void;
+    /**
+     * Removes all classes that start with tsg-* and sets box to null. It is needed so that control will
+     * release the box to be used for other widgets
+     */
+    unmount(): void;
+}
+
+export { TsBase, TsEvent, type TsEventData, type TsEventListener, type TsEventPayload, toSafeEvent };

package/dist/base.es6.js

@@ -0,0 +1,11 @@
+import {
+  TsBase,
+  TsEvent,
+  toSafeEvent
+} from "./chunks/chunk-DXZJHS4M.js";
+export {
+  TsBase,
+  TsEvent,
+  toSafeEvent
+};
+//# sourceMappingURL=base.es6.js.map

package/dist/base.es6.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}