@agridea/suibi-module 0.1.0-preview.8

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Agridea
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,120 @@
+# Agridea SuisseBilanz Module
+
+This is the Agridea SuisseBilanz Module, and its aim is to be a compliance module that can easily be integrated in other applications.
+
+**Current status:** Proof of concept, where the overall architecture gets clarified and tested. (we will update this along the way)
+
+Built as an Angular standalone app that ships as a Web Component (`<suibi-module>`).
+
+**Quick start (stable latest via unpkg):**
+```html
+<script type="module" src="https://unpkg.com/@agridea/suibi-module@latest/dist/elements/browser/main.js"></script>
+<suibi-module locale="en"></suibi-module>
+```
+
+**Preview (latest pre-release via unpkg):**
+```html
+<script type="module" src="https://unpkg.com/@agridea/suibi-module@preview/dist/elements/browser/main.js"></script>
+<suibi-module locale="en"></suibi-module>
+```
+
+**Pinned to a specific version (via unpkg, recommended for production):**
+```html
+<script type="module" src="https://unpkg.com/@agridea/suibi-module@0.1.0/dist/elements/browser/main.js"></script>
+<suibi-module locale="en"></suibi-module>
+```
+
+## Documentation
+- [Architecture](./doc/architecture.md) - Technical decisions, signals, Shadow DOM, i18n
+- [Web Component API](./doc/web-component-api.md) - Public attributes, properties, and emitted events
+	- Includes semantic versioning & distribution channel details (stable / preview)
+- [Theming](./doc/theming.md) - Theme bundle selection via `theme-src`
+- [Development Environment](./doc/development-environment.md) - Setup, build scripts, testing
+- [CI/CD](./doc/cicd.md) - GitHub Actions → Azure Static Web Apps (prod: `main`, staging: `develop`, PR previews)
+- [AI Tooling & MCP](./doc/ai-tooling.md)
+- [Master Data Automation](./doc/master-data.md) - NMD Arrays
+- [JSONForms Customizations](./doc/jsonforms-customizations.md) - Custom renderers & layout variants (card/plain/logical)
+ - [Schema & UI Helper Architecture](./doc/ui-schema-extensions.md) - Separation of domain schema, UI helpers, custom code lists
+
+## Quick Start
+
+### Prerequisites
+- Node.js 20+
+- npm 10+
+
+### Installation
+```bash
+npm ci
+```
+
+### Development (Angular SPA)
+```bash
+npm start
+```
+Open http://localhost:4200/
+
+### Build Web Component
+
+```bash
+npm run build:wc
+```
+
+Outputs (in `dist/elements/browser/`):
+- `main.js` (raw build)
+- `suibi-module-latest.js` / `.css` (synced to latest stable release)
+- `suibi-module-preview.js` / `.css` (synced to latest preview)
+- `suibi-module.vX.Y.Z.js` / `.css` (semantic versioned immutable artifact)
+- `version.txt` containing `<version> <git-sha>`
+
+For production, use a pinned version URL; stable/preview aliases are convenient for rapid development but may update unexpectedly.
+
+### NPM Package Consumption (Types & Bundled WC)
+
+The component is published to npm.org as `@agridea/suibi-module` with semantic versions.
+
+1. Install:
+   ```bash
+   npm install @agridea/suibi-module@latest   # or @preview for pre-release
+   ```
+2. Import types (optional):
+   ```ts
+   import type { NaebiData, PageId, Locale, EnrichedValidationError } from '@agridea/suibi-module';
+   ```
+
+For script-tag usage, prefer unpkg CDN (zero setup, no auth required). The npm install path is primarily for host apps needing TypeScript types or bundler-based integration.### Versioning & Release Channels
+
+| Channel  | Trigger                      | CDN URL Pattern           | Version pattern            | npm dist-tag |
+|----------|------------------------------|---------------------------|----------------------------|--------------|
+| Stable   | Git tag `vX.Y.Z` on `main`   | unpkg `@latest`           | `X.Y.Z`                    | `latest`     |
+| Preview  | Push to `develop`            | unpkg `@preview`          | `X.Y.Z-preview.<n>`        | `preview`    |
+
+**CDN usage (via unpkg):**
+- Stable latest: `https://unpkg.com/@agridea/suibi-module@latest/dist/elements/browser/main.js`
+- Preview latest: `https://unpkg.com/@agridea/suibi-module@preview/dist/elements/browser/main.js`
+- Pinned version: `https://unpkg.com/@agridea/suibi-module@X.Y.Z/dist/elements/browser/main.js`
+
+Rules / notes:
+- Semantic Versioning (MAJOR.MINOR.PATCH) for stable tags.
+- Preview builds increment `<n>` monotonically per base version (CI run counter) and are ephemeral (replaced on next develop push).
+- **For production:** pin to a versioned tag (`@X.Y.Z`) for immutability and cache stability.
+- **For development:** use `@latest` (stable) or `@preview` for convenience; expect updates.
+- All releases include `version.txt` (in GitHub Releases) with semver + git SHA for audit trails.
+
+### Fonts & Styles
+
+The bundle injects Roboto + Material Icons via Google Fonts for convenience. Production hosts with stricter CSP / offline needs can:
+1. Self-host fonts (place CSS before the script tag so the runtime detects them and skips injection), or
+2. Override via a custom theme stylesheet referenced with the `theme-src` attribute (fetched once at element connect).
+
+`styles.css` (and its versioned/alias variants) MUST be served adjacent to the JS bundle for automatic discovery. If you relocate files, ensure the relative path logic in `element.ts` still resolves (or adapt it locally).
+
+### Testing
+```bash
+npm test          # headed
+npm run test:headless
+```
+
+The test scripts auto-detect Chrome/Chromium binaries across different environments (devcontainer, CI, local setups). Override with `CHROME_BIN=/path/to/chrome npm test` if needed.
+
+For detailed development instructions, build options, and testing setup, see the [Development Environment](./doc/development-environment.md) guide.
+