[Stack 3/3] Composed components and contract baseline

.env

@@ -4,5 +4,7 @@ REACT_APP_FALLBACK_LANGUAGE="en"
 REACT_APP_GRAPHQL_API_URL="http://localhost:3001/api/graphql"
 REACT_APP_API_URL=""
 REACT_APP_VILNACRM_GMAIL=""
+REACT_APP_VILNACRM_PRIVACY_POLICY_URL=""
+REACT_APP_VILNACRM_USAGE_POLICY_URL=""
 REACT_APP_STORYBOOK_URL="http://localhost:6006"
 MEMLAB_WEBSITE_URL="http://localhost:3000"

.env.example

@@ -9,5 +9,9 @@ REACT_APP_API_URL="https://yourserver.io/api/"
 # Optional contact email for consumers that expose support/contact UI.
 REACT_APP_VILNACRM_GMAIL="support@yourdomain.example"
 
+# Optional footer policy links. Fall back to the VilnaCRM website defaults.
+REACT_APP_VILNACRM_PRIVACY_POLICY_URL="https://yourdomain.example/privacy-policy"
+REACT_APP_VILNACRM_USAGE_POLICY_URL="https://yourdomain.example/usage-policy"
+
 REACT_APP_STORYBOOK_URL="http://localhost:6006"
 MEMLAB_WEBSITE_URL="http://localhost:3000"

.qlty/qlty.toml

@@ -0,0 +1,96 @@
+# This file was automatically generated by `qlty init`.
+# You can modify it to suit your needs.
+# We recommend you to commit this file to your repository.
+#
+# This configuration is used by both Qlty CLI and Qlty Cloud.
+#
+#     Qlty CLI -- Code quality toolkit for developers
+#     Qlty Cloud -- Fully automated Code Health Platform
+#
+# Try Qlty Cloud: https://qlty.sh
+#
+# For a guide to configuration, visit https://qlty.sh/d/config
+# Or for a full reference, visit https://qlty.sh/d/qlty-toml
+config_version = "0"
+
+exclude_patterns = [
+  "*_min.*",
+  "*-min.*",
+  "*.min.*",
+  "**/.yarn/**",
+  "**/*.d.ts",
+  "**/assets/**",
+  "**/bower_components/**",
+  "**/build/**",
+  "**/cache/**",
+  "**/config/**",
+  "**/db/**",
+  "**/deps/**",
+  "**/dist/**",
+  "**/extern/**",
+  "**/external/**",
+  "**/generated/**",
+  "**/Godeps/**",
+  "**/gradlew/**",
+  "**/mvnw/**",
+  "**/node_modules/**",
+  "**/protos/**",
+  "**/seed/**",
+  "**/target/**",
+  "**/templates/**",
+  "**/testdata/**",
+  "**/vendor/**",
+]
+
+test_patterns = [
+  "**/test/**",
+  "**/spec/**",
+  "**/*.test.*",
+  "**/*.spec.*",
+  "**/*_test.*",
+  "**/*_spec.*",
+  "**/test_*.*",
+  "**/spec_*.*",
+]
+
+[smells]
+mode = "comment"
+
+[[source]]
+name = "default"
+default = true
+
+
+[[plugin]]
+name = "actionlint"
+
+[[plugin]]
+name = "editorconfig-checker"
+mode = "comment"
+
+[[plugin]]
+name = "eslint"
+package_file = "package.json"
+package_filters = ["eslint", "jest", "prettier"]
+
+[[plugin]]
+name = "hadolint"
+
+[[plugin]]
+name = "prettier"
+package_file = "package.json"
+package_filters = ["prettier"]
+
+[[plugin]]
+name = "radarlint-iac"
+mode = "monitor"
+
+[[plugin]]
+name = "ripgrep"
+mode = "comment"
+
+[[plugin]]
+name = "trufflehog"
+
+[[plugin]]
+name = "zizmor"

jest.config.ts

@@ -12,6 +12,8 @@ const config: Config = {
     '<rootDir>/tests/unit/**/*.spec.js',
   ],
   moduleNameMapper: {
+    '^swiper/css.*$': '<rootDir>/tests/unit/mocks/styleMock.ts',
+    '^swiper/(react|modules)$': '<rootDir>/tests/unit/mocks/swiperMock.tsx',
     '^.+\\.css$': '<rootDir>/tests/unit/mocks/styleMock.ts',
     '^.+\\.svg$': '<rootDir>/tests/unit/mocks/svgMock.ts',
     '^@/(.*)$': '<rootDir>/src/$1',

specs/implementation-artifacts/1-1-core-contract-and-export-baseline.md

@@ -0,0 +1,198 @@
+# Story 1.1: Core Contract and Export Baseline
+
+## Status
+
+review
+
+## Story
+
+As a consumer-team developer,
+I want core controls to expose a consistent public contract and entrypoint exports,
+so that I can integrate toolkit components predictably across company projects.
+
+## Acceptance Criteria
+
+1. Given the existing core control components are present, when their public props and export surface are inspected, then each core control has documented and typed contract fields aligned to the shared API policy (or a documented exception), and each core control is exported from `src/components/index.ts`.
+2. Given contract behavior is part of release quality gates, when contract verification checks are run, then failing export or contract mismatches are detectable before release, and the results block non-compliant changes.
+3. Given this epic must preserve compatibility, when contract adjustments are introduced, then existing public API behavior remains backward compatible unless explicitly approved, and any approved exception is documented.
+
+## Tasks / Subtasks
+
+- [x] Verify Story 1.1 execution preconditions and baseline files exist (AC: 1, 2, 3)
+  - [x] Confirm this is the full toolkit implementation checkout with `src/components/UiButton`, `src/components/UiInput`, `src/components/UiCheckbox`, `src/components/UiLink`, `src/components/index.ts`, `.storybook`, `package.json`, and the repo’s actual unit-test location (`tests/unit`).
+  - [x] If the implementation tree is missing, stop immediately and sync the real toolkit source checkout before changing code; do not create placeholder component code in the planning-only workspace.
+  - [x] Capture the current public prop surface for `UiButton`, `UiInput`, `UiCheckbox`, and `UiLink` before modifying contracts.
+- [x] Align core control contract typing without breaking published behavior (AC: 1, 3)
+  - [x] Normalize typed public props for the shared contract fields where relevant: `value`, `onChange`, `disabled`, `error`, `size`, `variant`, `sx`.
+  - [x] Document per-component contract exceptions where a field is not semantically valid; keep existing consumer-facing behavior backward compatible unless an explicit approval artifact exists.
+  - [x] Preserve the UI-only boundary: no backend integration, domain business logic, async orchestration, or hidden mutable side effects.
+- [x] Enforce core control export completeness at the package entry boundary (AC: 1, 2)
+  - [x] Ensure `UiButton`, `UiInput`, `UiCheckbox`, and `UiLink` are exported from `src/components/index.ts`.
+  - [x] Add or update an automated export/contract verification test in the repo’s unit-test suite so missing exports or contract regressions fail CI before release.
+  - [x] Record the verification command(s) and evidence in the story’s Dev Agent Record after tests pass.
+- [x] Finalize Story 1.1 evidence and compatibility notes (AC: 2, 3)
+  - [x] Document any approved contract exceptions and backward-compatibility decisions in code comments or adjacent type documentation where the repo already keeps public API notes.
+  - [x] Update any checklist or evidence artifact already present in the full checkout that is required to make export/contract failures release-blocking.
+  - [x] Re-run the targeted unit tests plus the repo’s relevant typecheck or lint command before marking the story complete.
+
+## Dev Notes
+
+### Story Foundation
+
+- Epic 1 establishes the baseline for all later component work. Story 1.1 is the contract/export gate for `UiButton`, `UiInput`, `UiCheckbox`, and `UiLink`; Story 1.2 and Story 1.3 depend on this baseline being stable first. [Source: specs/planning-artifacts/epics.md#story-11-core-contract-and-export-baseline]
+- The shared public contract policy is `value`, `onChange`, `disabled`, `error`, `size`, `variant`, and `sx`, with documented exceptions only where the component semantics require them. [Source: specs/planning-artifacts/prd.md#35-api-consistency-policy]
+- Public API completeness is enforced through `src/components/index.ts`; export integrity is a release gate, not a documentation nicety. [Source: specs/planning-artifacts/prd.md#78-quality-gates] [Source: specs/planning-artifacts/architecture.md#architectural-boundaries]
+
+### Technical Requirements
+
+- Keep the toolkit UI-only. No backend ownership, data fetching, retry logic, or domain workflow logic belongs in these controls. [Source: specs/planning-artifacts/prd.md#31-integration-boundary-hard-constraint] [Source: specs/planning-artifacts/architecture.md#api-communication-patterns]
+- Reuse-first and canonical behavior rules still apply to existing controls: behavior aligns to `crm`; `website` is only for visual or variant gap-fill. Any deviation must be documented. [Source: specs/planning-artifacts/prd.md#32-reuse-first-delivery-rule-hard-constraint] [Source: specs/planning-artifacts/prd.md#33-canonical-source-resolution]
+- Preserve backward compatibility for the current public APIs unless explicit approval exists. Contract cleanup cannot silently rename, remove, or change existing public behavior. [Source: specs/planning-artifacts/epics.md#story-11-core-contract-and-export-baseline] [Source: specs/planning-artifacts/prd.md#8-non-functional-requirements]
+- Event APIs should prefer existing React-native callback signatures unless a value-first contract is already established and documented in the current component. [Source: specs/planning-artifacts/architecture.md#format-patterns]
+
+### Architecture Compliance
+
+- Existing core controls are expected under legacy paths:
+  - `src/components/UiButton/`
+  - `src/components/UiInput/`
+  - `src/components/UiCheckbox/`
+  - `src/components/UiLink/`
+  - `src/components/index.ts`
+  - `tests/unit/UiButton.test.tsx`
+  - `tests/unit/UiInput.test.tsx`
+  - `tests/unit/UiCheckbox.test.tsx`
+  - `tests/unit/UiLink.test.tsx`
+    [Source: specs/planning-artifacts/architecture.md#requirements-to-structure-mapping]
+- Do not opportunistically migrate legacy `UiPascalCase` folders during this story. The migration path is intentionally deferred; Story 1.1 is about contract and export integrity only. [Source: specs/planning-artifacts/architecture.md#naming-patterns]
+- Public exports remain centralized in `src/components/index.ts` until a planned migration says otherwise. Internal component files are not public API. [Source: specs/planning-artifacts/architecture.md#structure-patterns] [Source: specs/planning-artifacts/architecture.md#architectural-boundaries]
+
+### File Structure Requirements
+
+- Expected full-checkout files for this story:
+  - `package.json`
+  - `.storybook/main.ts` and/or `.storybook/preview.ts`
+  - `src/components/UiButton/**`
+  - `src/components/UiInput/**`
+  - `src/components/UiCheckbox/**`
+  - `src/components/UiLink/**`
+  - `src/components/index.ts`
+  - `tests/unit/**`
+- Add new files only when directly required for Story 1.1 evidence, typically an export/contract regression test or adjacent public prop typing file. Keep scope out of Story 1.2 state parity work. [Source: specs/planning-artifacts/implementation-plan.md#task-3-epic-1-story-11-core-contract-and-export-baseline]
+
+### Testing Requirements
+
+- Minimum enforcement for this story:
+  - a targeted automated check that fails when a required core control export is missing from `src/components/index.ts`
+  - unit coverage for any public contract typing or prop-surface logic changed in core controls
+  - the repo’s relevant typecheck or lint command, if configured in the full checkout
+- Existing project testing standards are Jest plus Testing Library for unit coverage, with unit specs under `tests/unit`. [Source: specs/planning-artifacts/architecture.md#integration-test-conventions]
+- Story completion is blocked unless the new/updated tests exist and actually pass. [Source: specs/planning-artifacts/epics.md#story-11-core-contract-and-export-baseline] [Source: specs/planning-artifacts/prd.md#78-quality-gates]
+
+### Current Checkout Intelligence
+
+- This story artifact originated from planning-only workspace assumptions, but the current
+  working checkout on branch `7-make-ui-toolkit` is the real toolkit source tree. It contains
+  `src/`, `.storybook/`, `package.json`, and executable unit tests under
+  `tests/unit`; the planning-only inventory below describes the earlier planning
+  repository state, not the checkout where implementation and tests were run.
+- The implementation plan explicitly says Story execution must happen in the full toolkit source checkout and must stop if the source tree is missing. Treat that as a hard gate before TDD begins. [Source: specs/planning-artifacts/implementation-plan.md#execution-preconditions]
+- Recent git history is planning-focused only: `d1ebee0 specs: plan UI toolkit completion (PRD, architecture, epics)`, `ee44f87 feat(#3): add dependabot workflow (#4)`, `654a5bc Initial commit`. There is no recent component-implementation history in this checkout to mine for established prop patterns.
+
+### Latest Technical Information
+
+- This checkout has already upgraded to React `19.2` (`package.json` `react@^19.2.7`); the original planning artifacts targeted React 18, so treat React-19 APIs as available and keep the contract changes backward compatible with consumers. [Source: package.json] [Source: https://react.dev/versions]
+- This checkout uses MUI `v9` (`@mui/material@^9.0.1`), not the v5 the planning artifacts assumed; keep the shared `sx?: SxProps<Theme>` contract, which remains the supported typing in v9. [Source: package.json] [Source: specs/planning-artifacts/prd.md#35-api-consistency-policy]
+- This checkout uses Storybook `v10` (`storybook@^10.4.2`); the implementation plan referenced Storybook 8, so follow Storybook 10 (ESM-only) config semantics. [Source: package.json] [Source: https://storybook.js.org/blog/storybook-10]
+- Bun’s official docs currently advertise `v1.3.10`; this repo pins `bun@1.3.5` (`package.json` `packageManager`). Avoid relying on Bun features newer than the pinned version. [Source: package.json] [Source: https://bun.sh/]
+- This checkout uses TypeScript `v6` (`typescript@^6.0.3`); Story 1.1 only needs strict-mode compatibility with the repo’s current compiler settings — no further upgrade is required. [Source: package.json]
+
+### Project Structure Notes
+
+- No `project-context.md` file exists in this checkout.
+- Architecture expects future new components under feature-domain kebab-case paths, but Story 1.1 operates on legacy core controls that remain in `src/components/UiPascalCase/` until an explicit migration story exists. [Source: specs/planning-artifacts/architecture.md#naming-patterns]
+- If the full implementation checkout still differs from the planned architecture, document the variance in this story’s Dev Agent Record before making code changes. Do not “fix” unrelated structure drift as part of Story 1.1.
+
+### References
+
+- `specs/planning-artifacts/epics.md`
+- `specs/planning-artifacts/prd.md`
+- `specs/planning-artifacts/architecture.md`
+- `specs/planning-artifacts/implementation-plan.md`
+- `specs/implementation-artifacts/sprint-status.yaml`
+- https://react.dev/versions
+- https://react.dev/blog/2025/10/01/react-19-2
+- https://mui.com/versions/
+- https://storybook.js.org/blog/storybook-10
+- https://bun.sh/
+- https://bun.sh/docs/installation
+- https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-9.html
+
+## Dev Agent Record
+
+### Agent Model Used
+
+Codex GPT-5 (Amelia persona)
+
+### Debug Log References
+
+- 2026-03-09: Story created from planning artifacts after initializing sprint tracking.
+- 2026-03-09: Verified branch `7-make-ui-toolkit` contains the real toolkit source tree; the repo’s unit-test location is `tests/unit`, matching the planning artifacts.
+- 2026-03-09: All implementation edits and verification recorded in this Dev Agent Record were
+  executed in this checkout on branch `7-make-ui-toolkit`, not in the earlier planning-only
+  repository snapshot.
+- 2026-03-09: Added `UiCoreContract.test.tsx` first, watched it fail on missing `UiInput` `size` and `variant` forwarding plus missing Jest asset/module mappings, then implemented the minimal contract/export fixes.
+- 2026-03-09: Stabilized the existing Jest harness with CSS/SVG mocks, alias mapping, and explicit React imports/mock-factory adjustments required by the current `esbuild-jest` transform path.
+- 2026-03-09: Re-ran repository verification after implementation and moved the story to `review`.
+
+### Completion Notes List
+
+- Verified the executable repo uses `tests/unit` for unit specs, consistent with the story planning.
+- Normalized shared contract typing on `UiButton`, `UiInput`, `UiCheckbox`, and `UiLink` by moving `sx` to `SxProps<Theme>` and documenting invalid shared-field exceptions in adjacent type comments.
+- Extended `UiInput` public props with `size` and `variant`, forwarded both to MUI `TextField`, and kept existing consumer behavior backward compatible.
+- Added `tests/unit/UiCoreContract.test.tsx` to enforce package exports and the `UiInput` contract regression in CI.
+- Added Jest module mappings and test mocks for CSS/SVG assets, plus minimal React import/mock compatibility fixes required for the current unit-test transform pipeline.
+- Added a default fallback for `REACT_APP_VILNACRM_GMAIL` so the existing footer email test remains deterministic when the environment variable is absent.
+- Verification evidence:
+- `make lint-tsc` passed.
+- `make lint-next` exited successfully with pre-existing warnings only.
+- `bunx jest --verbose --runInBand` passed with `19` test suites and `52` tests.
+- Residual warning-only issues remain outside Story 1.1 scope: React `act(...)` noise around `UiTooltipWrapper`, nested `<p>` warnings in card/tooltip composition, uncontrolled-to-controlled warnings in `UiTextFieldForm`, and existing ESLint warnings reported by the make-based ESLint flow.
+
+### File List
+
+- jest.config.ts
+- specs/implementation-artifacts/1-1-core-contract-and-export-baseline.md
+- specs/implementation-artifacts/sprint-status.yaml
+- src/components/UiButton/index.tsx
+- src/components/UiButton/types.ts
+- src/components/UiCardItem/CardContent.tsx
+- src/components/UiCardList/CardGrid.tsx
+- src/components/UiCardList/CardSwiper.tsx
+- src/components/UiCardList/index.tsx
+- src/components/UiCheckbox/types.ts
+- src/components/UiFooter/DefaultFooter/DefaultFooter.tsx
+- src/components/UiFooter/UiFooter.tsx
+- src/components/UiFooter/VilnaCRMEmail/VilnaCRMGmail.tsx
+- src/components/UiImage/index.tsx
+- src/components/UiInput/index.tsx
+- src/components/UiInput/types.ts
+- src/components/UiLink/index.tsx
+- src/components/UiLink/types.ts
+- src/components/UiTextFieldForm/index.tsx
+- src/components/UiToolbar/index.tsx
+- tests/unit/mocks/styleMock.ts
+- tests/unit/mocks/svgMock.ts
+- tests/unit/UiButton.test.tsx
+- tests/unit/UiCardGrid.test.tsx
+- tests/unit/UiCardItem.test.tsx
+- tests/unit/UiCardList.test.tsx
+- tests/unit/UiCoreContract.test.tsx
+- tests/unit/UiFooterEmail.test.tsx
+- tests/unit/UiImage.test.tsx
+- tests/unit/UiTooltipWrapper.test.tsx
+
+## Change Log
+
+- 2026-03-09: Created Story 1.1 from PRD, architecture, epics, implementation plan, git history, and current repository inspection.
+- 2026-03-09: Implemented the core contract/export baseline, added contract regression coverage, and updated the Jest harness needed to execute the existing unit-test suite in this checkout.
+- 2026-03-09: Verified `lint:tsc`, `lint:next`, and the full Jest suite; story state advanced to `review` with warning-only residual risks documented in the Dev Agent Record.