@warkypublic/svelix 0.1.22 → 0.1.24

package/README.md

@@ -1,3 +1,52 @@
-# svelix
+# Svelix
 
-Svelix - Svelte UI tools
+Svelix is a Svelte 5 component library focused on workflow-heavy UI, data-rich views, and content tooling.
+
+## Install
+
+```bash
+pnpm add @warkypublic/svelix
+```
+
+## What ships
+
+- Svelte 5 components and helpers from the package root
+- published CSS assets under `@warkypublic/svelix/css/...`
+- LLM-oriented documentation under `@warkypublic/svelix/llm/...`
+
+## LLM Documentation
+
+The repository includes an `llm/` folder with project context and implementation docs.
+
+### In this repository
+
+- [llm/README.md](./llm/README.md)
+- [llm/ARCHITECTURE.md](./llm/ARCHITECTURE.md)
+- [llm/SETUP.md](./llm/SETUP.md)
+- [llm/COMPONENT_GUIDE.md](./llm/COMPONENT_GUIDE.md)
+- [llm/IMPLEMENTATION_PLAN.md](./llm/IMPLEMENTATION_PLAN.md)
+- [llm/ROADMAP.md](./llm/ROADMAP.md)
+- [llm/ESLINT_GUIDE.md](./llm/ESLINT_GUIDE.md)
+- [llm/tools/SVAR.md](./llm/tools/SVAR.md)
+- [llm/tools/resolvespec-js.md](./llm/tools/resolvespec-js.md)
+
+### After install
+
+The `llm/` docs are published with the package and can be accessed in either of these ways:
+
+- filesystem path: `node_modules/@warkypublic/svelix/llm/`
+- package subpath: `@warkypublic/svelix/llm/...`
+
+Examples:
+
+```text
+node_modules/@warkypublic/svelix/llm/README.md
+node_modules/@warkypublic/svelix/llm/ARCHITECTURE.md
+```
+
+```text
+@warkypublic/svelix/llm/README.md
+@warkypublic/svelix/llm/ARCHITECTURE.md
+```
+
+This makes the docs available to external tools and local LLM workflows that inspect installed package contents.

package/dist/components/Types/index.d.ts

@@ -0,0 +1 @@
+export type * from "./generic_grid";

package/dist/components/Types/index.js

@@ -0,0 +1 @@
+export {};

package/dist/components/index.d.ts

@@ -8,8 +8,8 @@ export * from "./Gridler/index";
 export * from "./SvarkGrid/index";
 export * from "./Portal/index";
 export * from "./OverlayStack/index";
-export * from "./Svark/index";
 export * from "./GlobalStateStore/index";
 export * from "./Screenshot/index";
 export * from "./VTree/index";
 export * from "./ContentEditor/index";
+export type * from "./Types/index";

package/dist/components/index.js

@@ -8,7 +8,7 @@ export * from "./Gridler/index";
 export * from "./SvarkGrid/index";
 export * from "./Portal/index";
 export * from "./OverlayStack/index";
-export * from "./Svark/index";
+//export * from "./Svark/index";
 export * from "./GlobalStateStore/index";
 export * from "./Screenshot/index";
 export * from "./VTree/index";

package/llm/ARCHITECTURE.md

@@ -0,0 +1,197 @@
+# Architecture Documentation
+
+## Technology Stack
+
+### Core Framework
+- **Svelte 5** (`^5.53.2`) with runes-based components
+- **SvelteKit 2** (`^2.53.0`) for library packaging and the demo app
+- **TypeScript 5** (`^5.9.3`) for typed component, adapter, and utility APIs
+
+### Styling
+- **Tailwind CSS v4** (`^4.2.0`) via `@tailwindcss/vite`
+- **Skeleton UI v4.12.0**
+  - `@skeletonlabs/skeleton`
+  - `@skeletonlabs/skeleton-svelte`
+- Published CSS entry points:
+  - `./css/tailwind-source.css`
+  - `./css/*.css`
+  - `./css/svelix_orange.css`
+
+### Development Tooling
+- **Storybook 10.2** for component docs and interactive examples
+- **Vitest 4** for unit tests plus Storybook-integrated browser tests
+- **Playwright 1.58** as the browser provider for Storybook/Vitest and for E2E coverage
+- **ESLint 10** with flat config and `eslint-plugin-svelte`
+- **publint** for package validation
+
+### Runtime Integrations
+- **`@svar-ui/svelte-grid`** for the SVAR-backed grid layer used by `SvarkGrid`
+- **`@warkypublic/resolvespec-js`** for ResolveSpec and RestHeaderSpec adapters
+- **Carta / Tipex / KaTeX / Monaco Editor** for `ContentEditor`
+- **`@js-temporal/polyfill`** for date-time handling
+
+## Project Structure
+
+```text
+svelix/
+├── .storybook/                 # Storybook config and Vitest browser setup
+├── llm/                        # AI-readable project docs
+├── src/
+│   ├── lib/
+│   │   ├── actions/            # Public action exports
+│   │   ├── components/         # Packaged components, adapters, stores, helpers
+│   │   ├── css/                # Published CSS assets
+│   │   ├── stores/             # Public store exports
+│   │   ├── utils/              # Shared utility exports
+│   │   └── index.ts            # Main package entry
+│   ├── routes/                 # Demo app
+│   └── app.html
+├── dist/                       # Package output from `pnpm package`
+├── package.json
+├── svelte.config.js
+└── vite.config.ts
+```
+
+## Public Package Surface
+
+### Top-level exports
+The main package entry currently re-exports:
+
+- `Button`
+- `ErrorBoundary`
+- `BetterMenu`
+- `Former`
+- `FormerControllers`
+- `Boxer`
+- `Gridler`
+- `SvarkGrid`
+- `Portal`
+- `OverlayStack`
+- `GlobalStateStore`
+- `Screenshot`
+- `VTree`
+- `ContentEditor`
+- shared generic grid types
+
+### Notable module families
+
+- **Form workflow**
+  - `Former`, `FormerModal`, `FormerDrawer`, `FormerButtonArea`
+  - `createFormerState`
+  - ResolveSpec / RestHeaderSpec form APIs
+  - controller components such as `TextInputCtrl`, `NumberInputCtrl`, `NativeSelectCtrl`, `PasswordInputCtrl`, `SwitchCtrl`, `TextAreaCtrl`, `DateTimeCtrl`, and action/button wrappers
+
+- **Data-heavy components**
+  - `Gridler` and `GridlerFull`
+  - Grid adapters, renderer helpers, scrolling/selection/cell cache utilities
+  - `SvarkGrid` with filtering, pagination, context-menu, and ResolveSpec-backed loading
+  - `VTree` with local or adapter-backed tree loading and search
+
+- **Application shell/state helpers**
+  - `GlobalStateStoreProvider`
+  - global state, i18n, and session helpers
+  - `overlayStack`, `registerOverlay`, `resolveOverlayLayer`
+
+- **Document/content workflows**
+  - `ContentEditor` for text, markdown, media, PDF, Monaco, and office-document flows
+  - `CaptureScreenshotComponent` and `CaptureScreen`
+
+### Internal or not yet top-level exported
+- `src/lib/components/Svark/` still exists with stories and adapters, but the package top-level export is currently commented out in [src/lib/components/index.ts](/home/hein/hein/dev/svelix/src/lib/components/index.ts#L1).
+- Consumers should treat `SvarkGrid` as the supported exported grid integration for now.
+
+## Build and Packaging Flow
+
+### Main scripts
+- `pnpm dev` runs the demo app
+- `pnpm storybook` runs Storybook on port `6006`
+- `pnpm build` builds the demo app and then packages the library
+- `pnpm package` runs:
+  1. `svelte-kit sync`
+  2. `svelte-package`
+  3. copies `src/lib/css/tailwind-source.css` into `dist/css/`
+  4. `publint`
+
+### Published output
+`package.json` publishes `dist/` and excludes tests, specs, and stories. The package exports both the main library entry and CSS entry points.
+
+## Testing Architecture
+
+### Vitest projects
+`vite.config.ts` defines two Vitest projects:
+
+- `unit`: runs `src/**/*.test.ts` in a Node environment
+- `storybook`: runs Storybook stories in a browser environment using Playwright
+
+### Additional test commands
+- `pnpm test`
+- `pnpm test:unit`
+- `pnpm test:watch`
+- `pnpm test:e2e`
+- `pnpm test:e2e:ui`
+
+## Styling Architecture
+
+### CSS import order
+Skeleton and Tailwind styles depend on import order:
+
+```css
+@import 'tailwindcss';
+@import '@skeletonlabs/skeleton';
+@import '@skeletonlabs/skeleton-svelte';
+@import '@skeletonlabs/skeleton/themes/cerberus';
+```
+
+This order is used in the app and Storybook preview styles.
+
+### Theme model
+- The default theme is **Cerberus**
+- Theme activation happens via `data-theme="cerberus"`
+- Component styling blends Skeleton primitives with custom utility/class composition
+
+## Architectural Patterns
+
+### Svelte 5 runes
+Most modern components use:
+- `$props()` for typed inputs
+- `$state()` for local mutable state
+- `$derived()` for computed values
+- `$effect()` for side effects
+- `Snippet` for render callbacks / slot-like composition
+
+### Adapter-first data access
+The data-heavy modules avoid hard-coding transport logic:
+- ResolveSpec and RestHeaderSpec adapters live alongside the components that consume them
+- component props accept adapter config and callback hooks
+- shared generic grid types are exported from `src/lib/components/Types/`
+
+### Overlay coordination
+Overlay-aware components use a shared stack model:
+- registration returns a stable `id`
+- z-index layers are derived from open order
+- portal or inline mount strategies are both supported
+
+### Rich editor extensibility
+`ContentEditor` is intentionally polymorphic:
+- detects content/editor mode from file metadata
+- supports Markdown and text editing
+- supports Monaco for code/text editing
+- supports Collabora and Office 365 WOPI flows for office files
+- exposes `insertText` and `insertHtml` callbacks for external integrations
+
+## Dependency Strategy
+
+### Peer dependencies
+- `svelte` is the only peer dependency today
+
+### Bundled/runtime dependencies
+Unlike the initial project setup, Svelix now has real runtime dependencies in `dependencies` for editor, markdown, math, and grid features. Consumers do not need to install those separately unless they are integrating at a lower level.
+
+### Dev-only dependencies
+Tooling such as Storybook, ESLint, Playwright, Vitest, and packaging utilities remain in `devDependencies`.
+
+## Current Focus Areas
+
+- keep the exported API aligned with the richer component set already present in `src/lib/components/`
+- continue hardening `SvarkGrid`, `Gridler`, `VTree`, and `ContentEditor`
+- decide whether legacy `Svark` should return as a top-level export or remain internal