Skip to content

🏗️ ConnectSoft Blazor Templates - Epics

Epic: EPIC-COMP-LIB — Component Library Template

Repository & Scaffolding (Foundations)

Create a clean, repeatable repo + solution scaffold for a tokens-first Blazor RCL with tests, docs, and dotnet new template packaging. Establish conventions so later cycles (tokens, components, adapters, tests, CI, packaging) plug in without churn.

Feature COMP-LIB-F01 — Initial Project Structure & Template Bootstrap

Outcome: A runnable solution with:

  • ConnectSoft.Blazor.ComponentLibrary (RCL)
  • ConnectSoft.Blazor.ComponentLibrary.Tests (MSTest + bUnit)
  • Gallery sample (minimal render host for manual checks)
  • template/.template.config (so this repo ships as a dotnet new template)
  • Standardized repo topology (+ analyzers, coding standards, global.json, source link)

Acceptance Criteria (DoD):

  • dotnet build succeeds locally and in CI.
  • dotnet new install (local template pack) produces a working scaffold.
  • Solution includes RCL, Tests, Gallery, Docs, Build folders.
  • Sample component renders in gallery page.
  • README documents how to create a project from the template.
Task COMP-LIB-T01 — Create Repo Layout & Solution

Title: Initialize repo, solution, and folder topology

Description: Create the baseline repo structure and add a .NET solution with three projects.

Implementation details:

  • Folders:

root/
  src/ConnectSoft.Blazor.ComponentLibrary/
  tests/ConnectSoft.Blazor.ComponentLibrary.Tests/
  samples/ConnectSoft.Blazor.ComponentLibrary.Gallery/
  build/pipelines/
  docs/
  template/.template.config/
* Create solution ConnectSoft.Blazor.ComponentLibrary.sln and add all three projects. * Add .gitignore (Visual Studio + .NET), LICENSE (MIT or chosen), README.md (scaffold usage). * Add global.json pinning .NET SDK (e.g., 9.0.x). * Add .editorconfig with nullable, style, analyzers severity.

Task COMP-LIB-T02 — RCL Project (Tokens-First Skeleton)

Title: Scaffold Razor Class Library with static web assets

Description: Create src/ConnectSoft.Blazor.ComponentLibrary as an RCL prepared to ship CSS tokens via static web assets.

Implementation details:

  • ConnectSoft.Blazor.ComponentLibrary.csproj:
    • <TargetFramework>net9.0</TargetFramework>
    • Enable nullable, implicit usings, XML docs, SourceLink.
    • GenerateDocumentationFile>true
    • EmitCompilerGeneratedFiles>false
    • IncludeBuildOutput>true
    • Static web assets: ensure wwwroot is included.
  • Seed minimal component (e.g., Primitives/Box.razor) with scoped CSS and tokens class placeholders.
  • Add wwwroot/css/placeholder.css (will be replaced by Cycle 2 Tokens).
  • Add AssemblyInfo.cs with [assembly: InternalsVisibleTo("ConnectSoft.Blazor.ComponentLibrary.Tests")].
Task COMP-LIB-T03 — Test Project (MSTest + bUnit)

Title: Set up MSTest + bUnit harness

Description: Create a test project with a reusable BunitTestContext base.

Implementation details:

  • tests/ConnectSoft.Blazor.ComponentLibrary.Tests.csproj:
    • MSTest V2 packages, bUnit, FluentAssertions.
    • <IsPackable>false</IsPackable>
  • Add TestHost.cs with Bunit.TestContext setup.
  • Add a smoke test that renders Primitives/Box and asserts markup is not empty.

Title: Create minimal gallery for manual checks

Description: A tiny Blazor Server (or WASM Hosted) sample to preview components.

Implementation details:

  • samples/ConnectSoft.Blazor.ComponentLibrary.Gallery:
    • Blazor Server app (fast inner loop).
    • Reference the RCL project.
    • Pages/Index.razor renders the Box component with different classes.
    • Add a navbar placeholder for future theme/density switches.
Task COMP-LIB-T05 — Build Quality & Analyzers

Title: Enable analyzers, warnings as errors, source link

Description: Add a shared Directory.Build.props/targets for all projects.

Implementation details:

  • build/Directory.Build.props:
    • <TreatWarningsAsErrors>true> (you can scope to projects if needed).
    • Roslyn analyzers package (internal or standard).
    • <ContinuousIntegrationBuild>true when $(GITHUB_ACTIONS) or $(TF_BUILD) set.
    • SourceLink + Deterministic builds config.
  • build/versioning.props (placeholder for SemVer & sourcelink).
Task COMP-LIB-T06 — Template Packaging Metadata

Title: Add dotnet new template config

Description: Make the repo export a template that scaffolds a new component library solution.

Implementation details:

  • template/.template.config/template.json:
    • "$schema": "http://json.schemastore.org/template", identity, groupIdentity, name, shortName
    • symbols (e.g., libraryName, company, license).
  • Add template/content/ pointing to a copy of src/, tests/, samples/ with tokens like __LibraryName__.
  • Ensure the template excludes bin/obj and keeps GUIDs templated.
  • Local install flow:
    • dotnet new install ./template
    • dotnet new cs-blazor-comp-lib -n MyCompany.MyLib (shortName TBD)
Task COMP-LIB-T07 — Repo Docs (User Guide)

Title: Author README & quickstart docs

Description: Document how to build, test, run gallery, and install the template.

Implementation details:

  • README.md:
    • “What is this”, “Prereqs”, “Build & Test”, “Run Gallery”, “Install Template”, “Create new lib”.
  • docs/ stub with getting-started.md and changelog.md (empty for now).
Task COMP-LIB-T08 — CI Bootstrap (Skeleton)

Title: Add minimal CI pipeline (build + tests)

Description: Provide a basic CI script to validate the scaffold.

Implementation details:

  • build/pipelines/ci.yml (Azure DevOps or GitHub Actions—choose one to start):
    • Steps: setup .NET SDK → restore → build → test.
    • Publish test results & artifacts.
  • Wire branch protection separately.
Task COMP-LIB-T09 — Local Dev Scripts

Title: Add helper scripts for inner loop

Description: Provide build.ps1 / build.sh and test.ps1 / test.sh.

Implementation details:

  • Scripts call dotnet restore, dotnet build -c Release, dotnet test --collect:"XPlat Code Coverage".
Task COMP-LIB-T10 — Smoke Validation

Title: Validate end-to-end developer flow

Description: Ensure everything works together before closing the phase.

Implementation details:

  • Clean clone, run:
    • dotnet build
    • dotnet test
    • Run Gallery dotnet run --project samples/...
    • dotnet new install ./template
    • dotnet new cs-blazor-comp-lib -n DemoOrg.DemoLib
  • Confirm the generated solution builds & runs.

Deliverables Checklist

  • ✅ Solution with RCL + Tests + Gallery
  • ✅ Template packaging metadata present
  • ✅ README with quickstart
  • ✅ CI skeleton committed
  • ✅ Analyzers + source link + reproducible builds

Design Tokens Integration

Feature COMP-LIB-F02 — Token-First Styling

Goal: Integrate the shared tokens package and Tailwind preset, replace the placeholder CSS, wire semantic classes across the RCL, and add quality gates (token-drift & contrast checks). Consumers must get tokens via static web assets, and the gallery should expose theme/density switches to validate live tokens. Consumption must follow the HLD guidance for RCL usage and semantic classes, not raw colors. DoD: Components render only semantic tokens; gallery toggles theme/density; CI runs contrast check and token-drift checks.

Task COMP-LIB-T11 — Tokens Package & Static Web Assets (E2E)

Title: Import tokens package and expose via static web assets

Description: Bring in the shared connectsoft.theme.tokens (CSS variables + utilities) and wire it into the RCL so downstream apps automatically receive tokens via static web assets. Replace placeholder.css.

Implementation details:

  • Add NuGet (or local project) reference to connectsoft.theme.tokens.
  • Copy/Include token CSS into wwwroot/css/ (e.g., tokens.css, tokens.dark.css, tokens.density.css, tokens.a11y.css) and ensure static web assets are published by the RCL.
  • Remove wwwroot/css/placeholder.css.
  • Confirm distribution approach aligns with HLD (“Publish as NuGet for .NET consumers (embed CSS files + static web assets)”). Acceptance Criteria (DoD):
  • Building the gallery shows tokenized surfaces/content colors; no raw color values used in components.
Task COMP-LIB-T12 — Tailwind Preset Integration (E2E)

Title: Wire Tailwind preset and build pipeline

Description: Integrate Tailwind using the Factory preset so Razor uses semantic utility classes (e.g., bg-surface-1, text-content).

Implementation details:

  • Add tailwind.config.cjs with presets: [require('@connectsoft/theme/tailwind/preset.cjs')].
  • Add postcss.config.cjs and NPM dev deps (tailwindcss, postcss, autoprefixer).
  • Ensure RCL build (and gallery) invokes Tailwind during build/watch (MSBuild target or npm script invoked by Target=_GenerateStaticWebAssets).
  • Add sample semantic classes in Components/ scoped CSS (remove any hardcoded hex). Acceptance Criteria (DoD):
  • dotnet build + npm run build (or MSBuild-invoked) produce a single minified CSS referencing only CSS variables from tokens.
Task COMP-LIB-T13 — Semantic Class Refactor & A11y States (E2E)

Title: Refactor baseline components to semantic tokens & add focus/validation states

Description: Update Button, TextField, and Modal to rely exclusively on semantic token classes and add focus rings and validation visuals consistent with tokens.

Implementation details:

  • Replace per-component style fragments with token-based classes:
    • Surfaces/Content: bg-surface-1, text-content
    • Action colors: map to --cs-action-* (bg/fg/hover)
    • Focus: ring color/width from token set
  • Ensure density influences paddings/heights via data-density contract.
  • Ensure theme switching works via data-theme="light|dark" and data-a11y="high-contrast". Acceptance Criteria (DoD):
  • No raw hex/RGB in components (caught by token-drift gate in T15).

Title: Implement theme (light/dark/a11y) and density (compact/cozy/comfortable) toggles in the gallery

Description: Add UI controls in the gallery to set data-theme, data-a11y, and data-density on the root, so reviewers can validate token behavior live.

Implementation details:

  • In the gallery layout, add toggles that set attributes on <html> or the root layout component.
  • Demonstrate live re-rendering of baseline components under different modes.
  • Follow HLD contract for theming/density attributes. Acceptance Criteria (DoD):
  • Switching modes updates visuals immediately across all showcased components.
Task COMP-LIB-T15 — CI Quality Gates: Token-Drift & Contrast (E2E)

Title: Add token-drift detector and WCAG contrast checks to CI

Description: Enforce no raw colors in components and validate contrast for key semantic pairs.

Implementation details:

  • Token-drift detector: a script that fails CI if component sources contain raw hex/RGB (allowlist tokens.css).
  • Contrast check: run an automated checker (e.g., axe/pa11y or custom) against gallery pages for (surface.*×content.*, action.bg×action.fg) pairs at AA.
  • Wire tasks into existing CI skeleton from Cycle 1. Acceptance Criteria (DoD):
  • CI fails when a raw color is introduced or when contrast falls below threshold.

Deliverables Checklist

  • ✅ Tokens package integrated; placeholder CSS removed and static web assets emit token CSS.
  • ✅ Tailwind preset wired; components use semantic utility classes only.
  • ✅ Gallery toggles theme/density per contract.
  • ✅ CI enforces token-drift and contrast gates.

Baseline Components (Button)

Feature COMP-LIB-F03 — Button Component

Goal: Provide a fully token-driven, accessible Button component as the first baseline building block of the component library. The Button should support multiple variants, sizes, states, and accessibility features, all validated in tests and showcased in the gallery. DoD: Button renders in gallery with all variants; tests cover visual states, events, and accessibility; no raw colors, only semantic tokens.

Task COMP-LIB-T17 — Implement Button Component

Title: Create token-driven Button with variants and sizes

Description: Build the Button.razor component with scoped CSS, supporting semantic tokens and variants (primary, secondary, danger, subtle). Implement parameters for size, disabled state, loading state, and icons. Ensure keyboard and accessibility features (ARIA roles, focus ring) are included.

Implementation details:

  • File: src/Components/Button.razor + Button.razor.css
  • Parameters: Variant, Size, Disabled, Loading, IconBefore, IconAfter
  • Styling: Tailwind preset classes, token variables for bg, fg, hover, focus
  • Accessibility: role="button", aria-disabled, tabindex, focus ring from tokens
  • Ensure density and theme switches are respected (data-density, data-theme)

Title: Showcase Button variants in gallery

Description: Add a dedicated page/section in the Gallery app to display all Button variants, sizes, and states, including light/dark/density modes. Provide copyable Razor snippets for developers.

Implementation details:

  • File: samples/Gallery/Pages/ButtonDemo.razor
  • Render matrix of: {primary, secondary, danger, subtle} × {sm, md, lg} × {enabled, disabled, loading}
  • Add theme/density toggle controls at top of demo page
  • Include example with icons (IconBefore, IconAfter)
Task COMP-LIB-T19 — Button Tests

Title: Add MSTest + bUnit tests for Button

Description: Write tests covering rendering, event handling, accessibility roles, disabled/ARIA state, loading indicator, and focus ring. Include snapshot tests for main variants.

Implementation details:

  • File: tests/ButtonTests.cs
  • Test cases:
    • Renders text content
    • Invokes OnClick when enabled, not when disabled
    • Applies correct classes for variant/size
    • Shows loading indicator when Loading=true
    • Focus ring present in keyboard navigation tests
  • Assert no raw tokens/hex codes in rendered markup

Baseline Components (TextField)

Feature COMP-LIB-F04 — TextField Component

Goal: Deliver a token-driven, accessible TextField input with full support for labels, helper/error text, prefix/suffix slots, and validation markers. Component must integrate with EditForm and follow the library’s accessibility and localization standards. DoD: TextField renders correctly in gallery across states and densities; validation integrates with Blazor forms; accessibility roles and ARIA attributes are present; bUnit tests cover controlled/uncontrolled usage.

Task COMP-LIB-T20 — Implement TextField Component

Title: Create token-driven TextField with validation states

Description: Build TextField.razor + scoped CSS to support text input, label, helper/error text, and validation styling. Add slots for prefix and suffix (icons or text). Respect UiOptions for density and reduced motion.

Implementation details:

  • Parameters: Label, HelperText, ErrorText, Required, Disabled, Prefix, Suffix, Value, ValueChanged
  • Styling:
    • Base classes: bg-surface-1, text-content, border-border-muted
    • Focus: focus:ring-[var(--cs-focus-ring)]
    • Validation: green/red token borders for valid/invalid states
  • Accessibility:
    • aria-invalid when ErrorText set
    • aria-required when Required true
    • Link label via for/id binding
  • Integration: Works with EditForm and ValidationMessage<T>

Title: Showcase TextField states in gallery

Description: Add gallery demo page for TextField, displaying default, disabled, required, with helper text, with error text, and with prefix/suffix icons. Show localization toggle for label/error strings.

Implementation details:

  • File: samples/Gallery/Pages/TextFieldDemo.razor
  • Demo matrix:
    • {default, disabled, required} × {with helper, with error}
    • Prefix: search icon example
    • Suffix: clear button example
  • Add code snippets for copy-paste into apps
  • Show theme/density/RTL toggles applied to TextField
Task COMP-LIB-T22 — TextField Tests

Title: Add MSTest + bUnit tests for TextField

Description: Write tests validating rendering, controlled/uncontrolled state, ARIA attributes, validation styling, prefix/suffix slots, and integration with EditForm.

Implementation details:

  • File: tests/TextFieldTests.cs
  • Test cases:
    • Renders label and helper/error text correctly
    • Required sets aria-required=true
    • Error state sets aria-invalid=true and error classes
    • Controlled binding: updates when Value set externally
    • OnChange event triggers ValueChanged
    • Prefix and suffix render correctly
    • Snapshot test with RTL culture

Baseline Components (Modal)

Feature COMP-LIB-F05 — Modal Component

Goal: Ship an accessible, token-driven Modal with header/body/footer slots, focus trap, ESC/overlay close, and size presets. Support both controlled (IsOpen) and uncontrolled modes, cancellable lifecycle events, and adapter-friendly framing. DoD: Modal demos render across sizes/themes/densities; keyboard/ARIA contracts verified; integration tests cover focus trap, ESC/overlay close, and labelled regions; no raw colors in component code.

Task COMP-LIB-T23 — Implement Modal (E2E)

Title: Build token-driven Modal with slots, focus trap, and lifecycle events

Description: Create Modal.razor (+ scoped CSS) that renders an overlay + centered panel using semantic tokens. Provide <Header>, <Body>, <Footer> slots; support IsOpen (controlled) with IsOpenChanged, and internal state (uncontrolled). Implement BeforeOpenAsync/BeforeCloseAsync (cancellable) and AfterOpenAsync/AfterCloseAsync. Respect CloseOnOverlay, EscToClose, InitialFocus, and Size (sm|md|lg|xl).

Implementation details:

  • Files: src/Components/Modal.razor, Modal.razor.css, Components/Primitives/FocusScope.razor (or small JS interop)
  • Tokens-first classes (examples): bg-surface-1 text-content rounded-lg shadow-cs4, overlay bg-[color:rgb(var(--cs-content-lo))]/40
  • ARIA: role="dialog", aria-modal="true", aria-labelledby (Header id), aria-describedby (Body id)
  • Keyboard: trap Tab/Shift+Tab, close on Escape when EscToClose=true
  • Overlay: click-to-close when CloseOnOverlay=true; ignore clicks inside panel
  • Density & theme: inherit via data-density, data-theme; spacing and radii via tokens
  • Adapter bridge: expose a light ModalFrame internal fragment so IUiDialogAdapter can host content similarly (future adapters align)
  • Prevent background scroll while open (class on <body> or root, removed on close)
  • Parameters (suggested):
    • bool? IsOpen, EventCallback<bool> IsOpenChanged
    • bool CloseOnOverlay = true, bool EscToClose = true, bool InitialFocus = true
    • string Size = "md"
    • RenderFragment? Header, RenderFragment? Body, RenderFragment? Footer
    • Func<CancellableArgs,Task>? BeforeOpenAsync/BeforeCloseAsync
    • Func<Task>? AfterOpenAsync/AfterCloseAsync

Title: Showcase Modal sizes, behaviors, and i18n/RTL in Gallery

Description: Add a Gallery page that demonstrates all sizes, overlay/ESC behavior toggles, controlled vs uncontrolled usage, and content-heavy scroll. Include localization switches (EN/RU/HE) and RTL mode to validate layout and focus order. Provide copyable examples for typical flows (confirm, form-in-modal).

Implementation details:

  • File: samples/Gallery/Pages/ModalDemo.razor

  • Demos:

  • Sizes: sm|md|lg|xl

  • Behaviors: CloseOnOverlay on/off, EscToClose on/off
  • Controlled example: parent manages IsOpen + IsOpenChanged
  • Form-in-modal: EditForm + validation summary/messages
  • Long body: verify scroll within panel; background locked
  • Top panel: theme/density toggles carried over; language selector + RTL switch
  • Include keyboard map (Tab/Shift+Tab, ESC) and ARIA ids shown in an “A11y” panel
Task COMP-LIB-T25 — Modal Tests

Title: Add MSTest + bUnit tests for Modal (focus, ESC, overlay, ARIA)

Description: Write rendering and interaction tests covering open/close flows, overlay clicks, ESC key handling, focus trap cycling, and ARIA attributes. Verify controlled/uncontrolled behavior and lifecycle event cancellation. Add snapshot tests per size.

Implementation details:

  • File: tests/ModalTests.cs
  • Cases:
    • Renders header/body/footer slots; assigns aria-labelledby/aria-describedby
    • IsOpen=true renders overlay and panel; IsOpen=false hides them
    • Overlay click closes when CloseOnOverlay=true; ignores when false
    • ESC closes when EscToClose=true; no effect when false
    • Focus trap cycles through tabbables; initial focus applied when InitialFocus=true
    • Controlled mode: toggling parent IsOpen updates rendering; IsOpenChanged fired
    • BeforeCloseAsync can cancel close; AfterCloseAsync invoked on success
    • Snapshot size matrix: sm|md|lg|xl (keep snapshots minimal/stable)

Accessibility Framework

Feature COMP-LIB-F06 — ARIA & Keyboard Navigation

Goal: Establish an accessibility foundation for the component library: shared ARIA helpers, robust keyboard navigation primitives (focus trap, roving tabindex, focus zones), and token-driven focus ring CSS with high-contrast support. Ensure every baseline component (Button, TextField, Modal) can consume these primitives consistently. DoD: Gallery demonstrates keyboard flows and live regions; components use helper APIs (no ad-hoc ARIA); CI runs axe/contrast checks; focus rings are token-driven and respect prefers-reduced-motion and high-contrast modes.

Task COMP-LIB-T26 — ARIA Helpers & Live Regions (E2E)

Title: Provide ARIA helper API + screen-reader live regions

Description: Add a small accessibility utility layer to standardize role/ID wiring, aria-labelledby/aria-describedby linking, and polite/assertive announcements via a LiveRegion service. Ship minimal CSS helpers (e.g., .sr-only) aligned with tokens.

Implementation details:

  • src/Accessibility/Aria.cs: helpers for generating stable IDs per component instance (Aria.MakeIds("header","body")), composing aria-* attributes, and common role contracts (Role.Dialog, Role.Button).
  • src/Accessibility/LiveRegion.razor + LiveRegionService: inject a single offscreen region; methods AnnouncePolite(string), AnnounceAssertive(string).
  • CSS: .sr-only and .sr-only-focusable utilities; ensure token-safe colors when needed (e.g., high-contrast outlines).
  • Integrations: wire Modal to announce open/close; TextField error messages announce on validation failure.
Task COMP-LIB-T27 — Keyboard Navigation Primitives (E2E)

Title: Implement FocusTrap, RovingTabIndex, and FocusZone patterns

Description: Create reusable primitives for keyboard navigation that components can adopt: a focus trap for modals/popovers, roving tabindex for menus/toolbar-like groups, and focus zones (horizontal/vertical/grid) with Arrow/Home/End semantics and Esc handling.

Implementation details:

  • src/Accessibility/FocusTrap.razor: contain focus within a scope; configurable initial focus; escape hatch for nested traps.
  • src/Accessibility/RovingTabIndex.cs: controller to assign one tabindex=0 item while others are -1; move with Arrow keys, Home/End.
  • src/Accessibility/FocusZone.razor: attach to a container; mode Horizontal|Vertical|Grid; maps Arrow keys to next focusable; supports RTL mirroring.
  • JS interop (minimal, if needed) for focus() and tabbables enumeration; otherwise prefer pure Blazor.
  • Apply primitives in existing components:
    • Modal → FocusTrap
    • Future Menu/List components → RovingTabIndex + FocusZone
    • Button groups (sample) → RovingTabIndex
Task COMP-LIB-T28 — Token-Driven Focus Ring & High-Contrast (E2E)

Title: Add focus ring CSS using tokens, :focus-visible, and a11y modes

Description: Create a unified focus appearance controlled by tokens (--cs-focus-ring, --cs-focus-width), using :focus-visible to avoid false positives. Provide high-contrast overrides and respect prefers-reduced-motion.

Implementation details:

  • src/Accessibility/FocusRing.css: utility classes (e.g., .cs-focus-ring) that apply tokenized outline/ring with offset; no inline styles.
  • Modes: default, high-contrast ([data-a11y="high-contrast"]), and reduced motion (disable animated outlines).
  • Replace per-component focus styles (Button, TextField, Modal) with shared utilities; ensure visible focus in all themes/densities.
Task COMP-LIB-T29 — A11y Test Harness & CI Gates (E2E)

Title: Add axe/contrast checks and keyboard simulations to CI

Description: Extend test setup to include automated accessibility checks and keyboard simulations for the gallery samples and core components. Fail CI on critical violations (contrast, missing labels, focus traps).

Implementation details:

  • bUnit tests: simulate key presses for FocusTrap/FocusZone; verify focus movement and ESC behavior.
  • Add an a11y runner (axe/pa11y via CLI against the Gallery dev server or prerendered pages); store reports as CI artifacts.
  • Contrast tests for semantic pairs (content vs surface, action.fg vs action.bg); enforce WCAG AA thresholds.
  • Wire into build/pipelines/ci.yml: run after unit tests; mark blockers as build failures with clear logs.

Title: Expose Accessibility panel and interactive keyboard demos in Gallery

Description: Create a dedicated “Accessibility” page in the Gallery that showcases: FocusTrap demo, roving tabindex list, FocusZone grid, and live region announcements. Include toggles for theme/density, high-contrast, and reduced motion to validate visual and behavioral consistency.

Implementation details:

  • samples/Gallery/Pages/AccessibilityDemo.razor: interactive sections:
    • FocusTrap demo (open modal, tab cycle, ESC to close).
    • RovingTabIndex demo (horizontal toolbar; Arrow/Home/End).
    • FocusZone grid (arrow navigation, wrap/nowrap).
    • LiveRegion buttons (announce polite/assertive messages).
  • Panel displays the role/ARIA map and the expected keyboard bindings for each demo.
  • Ensure all demos use the shared helpers/utilities from src/Accessibility/* (no one-off code).

Localization & Resources

Feature COMP-LIB-F07 — i18n Integration

Goal: Add first-class localization to the component library with RESX resources, IStringLocalizer wiring, RTL support, and culture switching in the Gallery. Ensure baseline components (Button, TextField, Modal) consume localized strings and that CI prevents missing keys/drift. DoD: Neutral + en, ru, he resources compiled; components use localizer; Gallery can switch language/RTL; tests validate rendering in multiple cultures; CI reports missing keys.

Task COMP-LIB-T31 — Localization Infrastructure (E2E)

Title: Enable localization services and project layout

Description: Wire AddLocalization in the library and gallery, define resources path, and establish a consistent RESX naming convention for shared strings and per-component strings.

Implementation details:

  • Library Services/Startup extension:
    • services.AddLocalization(options => options.ResourcesPath = "Localization");
  • Project layout:
    • src/ConnectSoft.Blazor.ComponentLibrary/Localization/Resources.resx (neutral)
    • Resources.en.resx, Resources.ru.resx, Resources.he.resx
    • Optional per-component bundles (e.g., Localization/Button.resx) if needed later.
  • Ensure satellite assemblies are generated for cultures.
Task COMP-LIB-T32 — Resource Authoring & Key Baseline (E2E)

Title: Create base RESX keys and translations for EN/RU/HE

Description: Define a minimal, reusable key set for baseline components and error/ARIA texts; populate neutral and culture-specific files.

Implementation details:

  • Keys (suggested):
    • Common.Close, Common.Cancel, Common.Save, Common.Required, Common.Loading
    • TextField.Label, TextField.Helper, TextField.Error
    • Modal.Title, Modal.CloseAria
    • Validation.RequiredMessage (format with {0} for field name)
  • Fill translations for en, ru, he (UTF-8).
  • Keep neutral as English; avoid duplicating Resources.en.resx unless needed for overrides.
Task COMP-LIB-T33 — Localizer Consumption in Components (E2E)

Title: Inject and use IStringLocalizer across baseline components

Description: Replace hardcoded strings in Button, TextField, and Modal with localized values. Add ARIA labels and descriptions using localizer.

Implementation details:

  • In each component: @inject IStringLocalizer<Resources> T
  • Examples:
    • Button loading: aria-label="@T["Common.Loading"]"
    • Modal close button: aria-label="@T["Modal.CloseAria"]"
    • TextField required asterisk tooltip: title="@T["Common.Required"]"
  • Keep keys centralized to avoid string scatter; refactor repeated literals into resources.

Title: Add language selector and RTL toggle to Gallery

Description: Allow runtime culture switching between en, ru, he and demonstrate RTL layout impact. Persist selection for the session and re-render demos.

Implementation details:

  • samples/Gallery add CultureService: sets CultureInfo.CurrentUICulture + CultureInfo.CurrentCulture.
  • UI: dropdown (EN, RU, HE) + [dir="rtl"] toggle (enabled when he selected; allow manual toggle for testing).
  • Propagate lang and dir attributes on root element; ensure tokens/layout remain intact under RTL.
  • Demo pages show localized strings and pluralization examples.
Task COMP-LIB-T35 — i18n Utilities, Plurals & Formatting (E2E)

Title: Provide helpers for pluralization and culture-aware formatting

Description: Add a small helper to handle simple plural rules and culture formatting for numbers/dates in samples.

Implementation details:

  • Localization/LocalizerExtensions.cs:
    • Plural(this IStringLocalizer T, string baseKey, int count) → uses ...One/...Other.
    • FormatCurrency/Date examples using CultureInfo.CurrentCulture.
  • Add sample usage in Gallery (cart items count; last updated date).
Task COMP-LIB-T36 — Tests & CI Guards for i18n (E2E)

Title: Add multi-culture render tests and missing-key detection

Description: Validate rendering under multiple cultures and fail CI on missing/unused resource keys.

Implementation details:

  • bUnit tests set culture (EN/RU/HE) and assert localized content appears.
  • Snapshot a minimal markup fragment per culture to catch regressions (keep stable).
  • Add a small analyzer/script in CI to:
    • detect missing keys across cultures,
    • warn on unused keys (best-effort),
    • block on empty translations in non-neutral files.
Task COMP-LIB-T37 — RTL Visual & A11y Verification (E2E)

Title: Verify RTL layout and ARIA/read order under Hebrew

Description: Ensure components preserve logical order and keyboard navigation in RTL.

Implementation details:

  • Gallery: toggle RTL and navigate Button/TextField/Modal with keyboard.
  • Confirm focus order is correct, caret and text alignment are sensible in TextField.
  • Adjust spacing utilities to logical start/end when necessary (e.g., ms-/me-).
Task COMP-LIB-T38 — Documentation: Localization Guide (E2E)

Title: Document resource keys, adding languages, and Gallery switches

Description: Author docs/i18n.md with key lists, culture setup steps, RTL notes, and examples.

Implementation details:

  • Include “How to add a new language” checklist.
  • Show component snippets with IStringLocalizer injection.
  • Describe CI checks for keys and how to fix failures.

Options & Configuration

Feature COMP-LIB-F08 — UiOptions System

Goal: Provide a simple, strongly-typed options system to configure library-wide UI behavior (theme/density/motion/RTL/high-contrast), with DI registration, validation, and runtime change notifications. Components should consume options via a lightweight context so apps can set global defaults and override per subtree when needed. DoD: UiOptions is registered and validated; components can read options; gallery exposes a Settings panel to switch options at runtime; tests cover binding, validation, and live updates.

Task COMP-LIB-T39 — Define UiOptions model with validation

Title: Create options class for theme, density, motion, and a11y modes

Description: Add a strongly-typed UiOptions model with sensible defaults and data annotations validation. Include enums for Density and Motion, and flags for HighContrast and Rtl. Provide a Validate() helper and map to data attributes for CSS tokens.

Implementation details:

  • src/Options/UiOptions.cs
    • Properties:
      • string Theme { get; set; } = "light";
      • Density Density { get; set; } = Density.Medium; // Compact|Medium|Comfortable
      • Motion Motion { get; set; } = Motion.Full; // Full|Reduced
      • bool HighContrast { get; set; } = false;
      • bool Rtl { get; set; } = false;
    • Validation via IValidatableObject or DataAnnotations (e.g., non-empty Theme).
    • ToAttributes() → returns dictionary (data-theme, data-density, data-a11y, dir).
  • src/Options/Enums.cs → Density, Motion.
Task COMP-LIB-T40 — DI registration & configuration binding

Title: Add service extension to register and bind UiOptions

Description: Provide AddComponentLibrary extension to register options with configuration binding and validation-on-startup. Allow optional delegate to override defaults during registration.

Implementation details:

  • src/DependencyInjection/ServiceCollectionExtensions.cs
    • public static IServiceCollection AddComponentLibrary(this IServiceCollection services, IConfiguration? config = null, Action<UiOptions>? configure = null)
    • Bind from config.GetSection("ConnectSoft:Ui") if provided.
    • services.AddOptions<UiOptions>().Bind(...).ValidateDataAnnotations().Validate(OnValidate).ValidateOnStart();
    • Expose IOptionsMonitor<UiOptions> to support live updates.
  • Unit test a minimal host that binds from in-memory config.
Task COMP-LIB-T41 — UiContext provider for runtime updates

Title: Implement UiContext cascading value for live option changes

Description: Add a lightweight context (CascadingValue) to broadcast current UI options and notify components on change. Include an API to request updates (SetOptions), backed by IOptionsMonitor<UiOptions> and local overrides.

Implementation details:

  • src/Options/UiContext.razor + UiContextService.cs
    • UiContext captures current UiOptions and exposes OnChanged event.
    • UiContextService.SetOptions(Action<UiOptions>) → updates current and triggers re-render.
    • When options change, set data attributes on root container to drive tokens:
      • data-theme, data-density (compact|cozy|comfortable), data-a11y="high-contrast" when enabled, dir="rtl" when Rtl.
  • Update Button/TextField/Modal samples to rely on attributes rather than internal state.
Task COMP-LIB-T42 — Component consumption helpers

Title: Provide utilities for components to read UiOptions and attributes

Description: Create an internal helper to safely read UiOptions from CascadingParameter with fallbacks, and a razor partial to emit standard data attributes at component boundaries if needed.

Implementation details:

  • src/Options/UiConsumption.cs
    • TryGetUiOptions(this ComponentBase, out UiOptions options)
    • ApplyUiAttributes(RenderTreeBuilder builder, UiOptions options) for container elements.
  • Refactor existing components to use helpers instead of duplicating logic.

Title: Add Settings panel to tweak options at runtime

Description: In Gallery, build a Settings panel that manipulates UiContext live (theme, density, motion, RTL, high-contrast). Persist choices in localStorage and restore on load.

Implementation details:

  • samples/Gallery/Shared/SettingsPanel.razor
    • Controls: Theme (light/dark), Density (compact/medium/comfortable), Motion (full/reduced), High-Contrast (on/off), RTL (on/off).
    • UiContextService.SetOptions(opts => { ... }) on change.
    • Persist via IJSRuntime localStorage; restore at startup.
  • Ensure changes update tokens immediately via root attributes.
Task COMP-LIB-T44 — Tests: binding, validation, and live updates

Title: Cover options binding and runtime update behavior

Description: Add tests to verify configuration binding, validation failures, and that components react to UiContext updates without reload (e.g., density/contrast changes reflected in class/attribute output).

Implementation details:

  • tests/UiOptionsTests.cs
    • Bind from dictionary config; assert defaults + overrides.
    • Invalid theme → validation fail.
  • tests/UiContextTests.cs
    • Render a dummy component reading options; call SetOptions; assert re-rendered attributes.
    • Verify data attributes applied to root correctly (data-density, data-theme, data-a11y, dir).
Task COMP-LIB-T45 — Documentation: Options & Theming guide

Title: Author docs/options-and-configuration.md with examples

Description: Document configuration via appsettings and code, runtime overrides via UiContext, and how attributes drive tokens. Include troubleshooting for validation errors and recommended defaults per product.

Implementation details:

  • Show appsettings.json sample under ConnectSoft:Ui.
  • Demonstrate per-page override with nested UiContext.
  • Explain interaction with localization (RTL) and accessibility (high-contrast, reduced motion).
  • Cross-link to Gallery Settings panel and token docs.

UI Kit Adapter Contracts

Feature COMP-LIB-F09 — Define IUiKitAdapter Interfaces

Goal: Establish UI-kit-agnostic adapter contracts for Dialog, Toast, and Validation so the component library can plug into any design system (Flowbite/DaisyUI/custom) without forking component logic. Provide DI registration, a safe Null fallback, async patterns, a11y semantics, and gallery stubs to prove end-to-end flows. DoD: Interfaces published with XML docs; DI extension exposes adapter registry; default Null adapters function without crashing; gallery shows working stubs for confirm/alert/prompt and toasts; validation messages route through the adapter.

Task COMP-LIB-T46 — Core Abstractions & Contracts (E2E)

Title: Define adapter interfaces and shared models for Dialog/Toast/Validation

Description: Create IUiDialogAdapter, IUiToastAdapter, and IUiValidationAdapter plus common option/result models and enums. Include XML docs and cancellation support.

Implementation details:

  • Namespace: ConnectSoft.Blazor.ComponentLibrary.Adapters
  • Files:
    • IUiDialogAdapter.cs → AlertAsync, ConfirmAsync, PromptAsync, ShowAsync(DialogRequest, CancellationToken) → returns DialogResult
    • IUiToastAdapter.cs → ShowAsync(ToastRequest), DismissAsync(Guid id), ClearAsync()
    • IUiValidationAdapter.cs → ShowFieldError(FieldIdentifier, string), ClearFieldError(FieldIdentifier), ShowSummary(IEnumerable<string>), ClearSummary()
    • Models/enums: DialogRequest, DialogKind { Alert, Confirm, Prompt, Custom }, DialogResult { Accepted, Rejected, Canceled, Value }, ToastLevel { Info, Success, Warning, Error }, ToastRequest { Id, Level, Title, Message, DurationMs, Closable }
  • Patterns:
    • All public async methods accept CancellationToken
    • Results are immutable records; IDs as Guid
    • XML comments specify a11y expectations (e.g., role=dialog, aria-modal)
Task COMP-LIB-T47 — DI Registration & Adapter Registry (E2E)

Title: Provide AddUiKitAdapters DI extension with safe defaults

Description: Add a registry that resolves adapters via DI with sensible Null defaults so apps work without a kit. Allow per-feature overrides (only Dialog, only Toast, etc.).

Implementation details:

  • ServiceCollectionExtensions.AddUiKitAdapters(Action<UiKitAdapterOptions>? configure = null)
  • UiKitAdapterOptions with properties: DialogAdapterType, ToastAdapterType, ValidationAdapterType
  • Register interfaces with:
    • Defaults: NullDialogAdapter, NullToastAdapter, NullValidationAdapter
    • Optional TryAdd + Replace pattern for overrides
  • Provide IUiDialogService, IUiToastService, IUiValidationService thin facades that delegate to adapters (keep components decoupled)
Task COMP-LIB-T48 — Dialog Contract & Bridge Components (E2E)

Title: Implement dialog service facade and a minimal bridge over Modal

Description: Build UiDialogService that exposes high-level APIs (AlertAsync, ConfirmAsync, PromptAsync). Provide a default BridgeDialogAdapter that composes the existing Modal component to satisfy the adapter contract.

Implementation details:

  • UiDialogService calls the registered IUiDialogAdapter
  • BridgeDialogAdapter renders a Modal with header/body/footer and buttons; supports:
    • Alert (OK), Confirm (OK/Cancel), Prompt (input + OK/Cancel)
    • DialogRequest → maps to localized labels via IStringLocalizer
  • a11y: set role="dialog", aria-labelledby/aria-describedby
  • Respect UiOptions for density/theme/high-contrast
  • Return DialogResult consistently; cancel on overlay/ESC where enabled
Task COMP-LIB-T49 — Toast Contract & Host (E2E)

Title: Implement toast service and a default in-library toast host

Description: Build UiToastService and a default BridgeToastAdapter that renders a toast host in the app shell (gallery + consumer apps). Support stacking, auto-dismiss, focus management, and a11y live regions.

Implementation details:

  • UiToastService → ShowAsync(ToastRequest) returns Guid, DismissAsync(Guid), ClearAsync()
  • BridgeToastAdapter:
    • Host component ToastHost.razor (portal region)
    • Announce via LiveRegionService for screen readers
    • Token-driven styles; positions: top-right by default
    • Auto-dismiss with pause-on-hover; manual close
  • Wire host into Gallery MainLayout and document how apps can add it
Task COMP-LIB-T50 — Validation Contract Integration (E2E)

Title: Connect validation adapter to EditContext and components

Description: Implement UiValidationService that subscribes to EditContext events and forwards field/summarized errors to the adapter. Provide default BridgeValidationAdapter that displays inline messages next to fields and a summary area.

Implementation details:

  • UiValidationService.Attach(EditContext) → listen to OnValidationRequested and OnFieldChanged
  • For each message, call adapter methods; clear when resolved
  • BridgeValidationAdapter renders:
    • Field message zone for TextField (or generic ValidationMessage<T>)
    • Summary region (tokenized alert component)
  • Localize common messages; ensure ARIA aria-invalid, aria-describedby

Title: Expose working stubs and a dynamic adapter switch in Gallery

Description: Add a Gallery “Adapters” page with runtime switch between Bridge (in-library) and Null adapters to demonstrate behavior and integration points for future Flowbite/DaisyUI adapters.

Implementation details:

  • Selector: Adapter Mode = { Bridge, Null }
  • Demos:
    • Dialogs: Alert/Confirm/Prompt
    • Toasts: Info/Success/Warning/Error (auto-dismiss + manual)
    • Validation: simple form showing field and summary errors
  • Display code snippets for registering a custom adapter in DI
Task COMP-LIB-T52 — Tests: Contracts & DI (E2E)

Title: Add unit/integration tests for services, results, and fallbacks

Description: Verify DI registration paths, Null adapters’ no-op safety, Bridge adapters’ observable behavior, and service cancellation.

Implementation details:

  • tests/Adapters/UiDialogServiceTests.cs: confirm/alert/prompt flows return expected DialogResult
  • tests/Adapters/UiToastServiceTests.cs: show/dismiss/clear updates host state
  • tests/Adapters/UiValidationServiceTests.cs: EditContext events produce field/summary calls
  • DI tests: replacing one adapter doesn’t affect others (partial overrides)
Task COMP-LIB-T53 — Documentation: Adapter Guide (E2E)

Title: Write docs/adapters.md and samples for custom kits

Description: Document the contracts, DI registration, the Bridge/Null adapters, and how to implement a custom kit adapter. Include minimal examples and a checklist for a11y and tokens.

Implementation details:

  • Sections: Concepts, Interfaces, DI, Bridge/Null reference, Creating a custom adapter, A11y requirements, Tokens & theming
  • Provide a complete sample of a custom IUiToastAdapter registering via AddUiKitAdapters(...)
  • Cross-link to Gallery “Adapters” page and to the Modal/TextField/Toast demos

Default Tokens Adapter

Feature COMP-LIB-F10 — TokensAdapter Implementation

Goal: Provide first-party adapters for Dialog, Toast, and Validation that are styled purely with our design tokens (no external UI kit). Ship as a small, optional package that apps can enable via DI. Must respect UiOptions (theme/density/motion/a11y/RTL) and the accessibility framework (focus rings, live regions, ARIA). DoD: Tokens adapters registered and selectable; gallery can switch to “Tokens” mode; dialogs/toasts/validation work end-to-end; tests cover behaviors and a11y; no raw colors (only semantic tokens).

Task COMP-LIB-T54 — Tokens Adapter Package & DI (E2E)

Title: Create Adapters.Tokens project and DI registration

Description: Scaffold a dedicated project for the tokens-based adapters, wire its DI extension, and ensure static web assets (CSS) are emitted alongside the RCL. Provide a single-line enablement API for consumers.

Implementation details:

  • Project: src/Adapters/ConnectSoft.Blazor.ComponentLibrary.Adapters.Tokens/
  • Add AddTokensUiKitAdapters(this IServiceCollection) that:
    • Registers IUiDialogAdapter, IUiToastAdapter, IUiValidationAdapter with Tokens implementations.
    • Keeps compatibility with AddUiKitAdapters(...); tokens adapters can Replace existing defaults.
  • Static web assets: wwwroot/css/tokens-adapters.css with minimal layout helpers (positions, z-index, transitions) using tokens and Tailwind preset utilities.
  • Docs XML enabled; package metadata set for NuGet.
Task COMP-LIB-T55 — DialogTokensAdapter (E2E)

Title: Implement tokens-styled dialog adapter over Modal primitives

Description: Implement DialogTokensAdapter that composes the library’s Modal with token presets for alert/confirm/prompt/custom flows, localized labels, and full a11y (role, aria labels, focus trap).

Implementation details:

  • Class: DialogTokensAdapter : IUiDialogAdapter
  • Map DialogRequest → header/body/footer layout with tokenized classes (surface, elevation, spacing, density).
  • Buttons: use Button component with variant mapping (primary/surface/subtle) and loading/disabled states.
  • a11y:
    • role="dialog", aria-modal="true", aria-labelledby/aria-describedby
    • ESC/overlay behavior from request; announce open/close via LiveRegionService.
  • Respect UiOptions (theme/RTL/high-contrast/motion).
  • Return DialogResult consistently; cancelable on close.
Task COMP-LIB-T56 — ToastTokensAdapter + Host (E2E)

Title: Implement tokens-styled toast host and adapter

Description: Implement ToastTokensAdapter with a reusable ToastHost region styled by tokens. Support levels (Info/Success/Warning/Error), stacking, auto-dismiss with pause-on-hover, manual close, and screen-reader announcements.

Implementation details:

  • Components:
    • ToastHost.razor (portal region) + ToastItem.razor
  • Adapter: ToastTokensAdapter : IUiToastAdapter
    • ShowAsync(ToastRequest) returns Guid
    • DismissAsync(Guid), ClearAsync()
  • Styles:
    • Position top-right; responsive offsets; elevation tokens (shadow-*).
    • Level → tokenized accent and icon.
  • a11y:
    • Live region announcements (polite for info/success, assertive for error).
    • Focus management for dismiss buttons.
Task COMP-LIB-T57 — ValidationTokensAdapter (E2E)

Title: Implement validation adapter for field and summary outputs

Description: Implement ValidationTokensAdapter that renders inline field messages and a summary area using tokenized alert styles. Integrate with UiValidationService and Blazor EditContext.

Implementation details:

  • Adapter: ValidationTokensAdapter : IUiValidationAdapter
  • Field messages:
    • Associate via aria-describedby and id linking.
    • Tokenized colors for error/warning/info; compact density affects spacing.
  • Summary:
    • Tokenized alert block with list of errors; anchor to first invalid field.
  • RTL/High-contrast aware; respects reduced motion for entry animations.

Title: Add “Tokens” adapter mode and live demos in Gallery

Description: Extend Gallery “Adapters” page to add Tokens mode. Demonstrate dialogs (alert/confirm/prompt), toasts (all levels), and validation with forms. Provide copyable DI snippets.

Implementation details:

  • Switcher: { Null | Bridge | Tokens }
  • Demos:
    • Dialog: destructive confirm (danger mapping), long content with scroll, prompt with validation.
    • Toast: stacked, auto-dismiss, manual close.
    • Validation: EditForm with field errors & summary.
  • Show one-click code snippet:
services.AddUiKitAdapters()
        .AddTokensUiKitAdapters();
Task COMP-LIB-T59 — Tests for Tokens Adapters (E2E)

Title: Add unit/integration tests for tokens adapters behavior

Description: Cover dialog result paths, toast lifecycle, and validation rendering. Verify a11y attributes, live region calls, RTL layout, and that no raw colors exist (token-drift gate).

Implementation details:

  • tests/Adapters/Tokens/DialogTokensAdapterTests.cs: alert/confirm/prompt flows, cancel on ESC/overlay.
  • tests/Adapters/Tokens/ToastTokensAdapterTests.cs: show/dismiss/auto-expire; live region assertions.
  • tests/Adapters/Tokens/ValidationTokensAdapterTests.cs: field and summary rendering, ARIA linkage.
  • Snapshot minimal markup for each adapter; enforce no hex/RGB via existing CI script.
Task COMP-LIB-T60 — Documentation & Migration Notes (E2E)

Title: Document Tokens Adapter usage and customization

Description: Create docs/adapters-tokens.md explaining DI setup, theming via UiOptions, customization (positions, durations, button labels), and a11y guarantees. Include a comparison with Bridge and guidance on when to choose Tokens vs external UI kits.

Implementation details:

  • Sections: Setup, Dialog patterns, Toast patterns, Validation patterns, Theming/RTL/HC, Extensibility points.
  • Include troubleshooting (e.g., missing host, z-index conflicts, reduced motion expectations).
  • Cross-link to Adapters guide and Options & Configuration.

Optional Flowbite Adapter

Feature COMP-LIB-F11 — Flowbite Adapter Package

Goal: Provide an optional adapter package that maps our Dialog/Toast/Validation contracts to the Flowbite UI kit (Tailwind-based). Ship a clean DI extension, static assets, and host components that render Flowbite-compliant markup and behaviors while respecting UiOptions (theme, density, motion, RTL) and our accessibility primitives. DoD: New package builds and registers via one-liner; Gallery exposes a “Flowbite” mode; dialogs/toasts/validation rendered with Flowbite classes and JS behaviors; tests cover adapter behaviors and DI swaps; docs explain setup and theming caveats.

Task COMP-LIB-T61 — Package Scaffold & DI Registration (E2E)

Title: Create Adapters.Flowbite project with one-line DI enablement

Description: Add a new RCL project that emits Flowbite-styled components and a DI extension to register Flowbite adapters for Dialog/Toast/Validation. Ensure compatibility with existing AddUiKitAdapters and that Flowbite can replace previous adapters cleanly.

Implementation details:

  • Project: src/Adapters/ConnectSoft.Blazor.ComponentLibrary.Adapters.Flowbite/
  • DI: services.AddUiKitAdapters().AddFlowbiteUiKitAdapters();
    • Replace IUiDialogAdapter, IUiToastAdapter, IUiValidationAdapter with Flowbite implementations
  • Enable XML docs + NuGet metadata; include wwwroot for Flowbite-specific CSS shims (if any)
  • Keep tokens-first: rely on semantic utilities + Flowbite classes; never hardcode colors
Task COMP-LIB-T62 — Flowbite Assets & Tailwind Wiring (E2E)

Title: Wire Flowbite CSS/JS and Tailwind plugin into build

Description: Configure Tailwind to include Flowbite plugin/utilities for the Gallery and for consumer apps; ship a minimal JS initializer for behaviors (modals/toasts) and ensure it plays nicely with Blazor lifecycle.

Implementation details:

  • Add Flowbite NPM deps to Gallery (and docs on how consumers add it)
  • Tailwind: include flowbite/plugin in tailwind.config.cjs
  • JS interop: flowbite.init.js that re-initializes when components render/patch DOM
  • Provide guidance for consumer apps: add Flowbite JS to layout and call init on OnAfterRenderAsync
  • Static web assets: include optional shims (spacing/z-index) under wwwroot/css/flowbite-bridge.css
Task COMP-LIB-T63 — DialogFlowbiteAdapter (E2E)

Title: Implement Flowbite dialog adapter using Flowbite modal markup

Description: Map IUiDialogAdapter to Flowbite’s modal patterns. Compose header/body/footer with Flowbite classes, connect buttons, and integrate focus trap + ESC/overlay handling; respect UiOptions and a11y contracts.

Implementation details:

  • DialogFlowbiteAdapter : IUiDialogAdapter
  • Render Flowbite modal container + overlay; size presets map to Flowbite width classes
  • Buttons use Flowbite button classes (btn, btn-primary, btn-outline mapping to variants)
  • Wire ESC/overlay close; ensure trap via our FocusTrap or Flowbite’s handling; announce via LiveRegionService
  • Localize labels via IStringLocalizer; ensure role="dialog", aria-modal, aria-labelledby/aria-describedby
Task COMP-LIB-T64 — ToastFlowbiteAdapter + Host (E2E)

Title: Implement Flowbite toast adapter and host region

Description: Render Flowbite toasts with stacking, levels (info/success/warning/error), auto-dismiss, and manual close. Use live regions for announcements and ensure keyboard focus for the close button.

Implementation details:

  • ToastFlowbiteAdapter : IUiToastAdapter
  • Host: FlowbiteToastHost.razor anchored in layout; position top-right with Flowbite utility classes
  • Levels map to Flowbite alert styles/icons
  • Auto-dismiss with pause-on-hover; manual dismissal updates state and screen reader announcement
  • Respect reduced motion and high-contrast via tokens/attributes
Task COMP-LIB-T65 — ValidationFlowbiteAdapter (E2E)

Title: Implement Flowbite validation adapter for field and summary

Description: Show field-level errors and a summary panel using Flowbite form/alert styles. Integrate with UiValidationService and preserve ARIA relationships to inputs.

Implementation details:

  • ValidationFlowbiteAdapter : IUiValidationAdapter
  • Field messages render under inputs with Flowbite text/error classes; link via aria-describedby
  • Summary renders with Flowbite alert component; optional anchors to invalid fields
  • Density-aware spacing; RTL-safe icon alignment
Task COMP-LIB-T66 — UiOptions → Flowbite Bridge (E2E)

Title: Map UiOptions (theme/density/motion/RTL) to Flowbite classes

Description: Ensure Flowbite markup responds correctly to our options. Provide a small mapping layer and CSS shims where Flowbite has gaps (e.g., densities).

Implementation details:

  • Theme: respect light/dark using data-theme or class="dark"
  • Density: add density classes (.density-compact|cozy|comfortable) that tweak paddings on Flowbite elements
  • Motion: suppress transitions when reduced motion is set
  • RTL: set logical margins/paddings and icon flips via logical utilities

Title: Add “Flowbite” mode to Adapters page with end-to-end demos

Description: Extend Gallery adapters switch to include “Flowbite”. Demonstrate dialogs (alert/confirm/prompt), toasts (all levels), and validation in a sample form. Show copyable DI and Tailwind config snippets.

Implementation details:

  • Switcher: { Null | Bridge | Tokens | Flowbite }
  • Demos mirror Tokens demos to compare behavior/visuals
  • Include setup panel with:
    • services.AddUiKitAdapters().AddFlowbiteUiKitAdapters();
    • tailwind.config.cjs Flowbite plugin snippet
    • Script include for Flowbite JS and init guidance
Task COMP-LIB-T68 — Tests & Docs (E2E)

Title: Add adapter tests and author Flowbite setup guide

Description: Cover dialog/ toast/ validation behaviors with Flowbite implementations; add documentation page covering installation, Tailwind integration, JS init, and theming/RTL tips.

Implementation details:

  • Tests:
    • tests/Adapters/Flowbite/DialogFlowbiteAdapterTests.cs
    • tests/Adapters/Flowbite/ToastFlowbiteAdapterTests.cs
    • tests/Adapters/Flowbite/ValidationFlowbiteAdapterTests.cs
    • Verify DI replacement, result paths, ARIA attributes, and live-region calls
  • Docs: docs/adapters-flowbite.md
    • Setup prerequisites (Tailwind + Flowbite plugin/JS)
    • DI registration, Gallery verification steps
    • UiOptions mapping table and troubleshooting (z-index, motion, density)

Optional DaisyUI Adapter

Feature COMP-LIB-F12 — DaisyUI Adapter Package

Goal: Ship an optional adapter package that maps our Dialog/Toast/Validation contracts to the DaisyUI Tailwind kit. Provide clean DI enablement, Tailwind/JS wiring notes, and host components that render DaisyUI-compliant markup/behavior while honoring UiOptions (theme, density, motion, RTL) and our a11y primitives. DoD: New package builds and registers with a one-liner; Gallery exposes a “DaisyUI” mode; dialogs/toasts/validation render with DaisyUI classes and behaviors; tests cover adapter behavior and DI swaps; docs explain setup, theming, and caveats.

Task COMP-LIB-T69 — Package Scaffold & DI Registration (E2E)

Title: Create Adapters.DaisyUI project with one-line DI enablement

Description: Add a new RCL project that emits DaisyUI-styled components and a DI extension registering DaisyUI adapters for Dialog/Toast/Validation. Ensure compatibility with AddUiKitAdapters and enable clean replacement of existing adapters.

Implementation details:

  • Project: src/Adapters/ConnectSoft.Blazor.ComponentLibrary.Adapters.DaisyUI/
  • DI:

services.AddUiKitAdapters()
        .AddDaisyUiKitAdapters();
* Replace interfaces: IUiDialogAdapter, IUiToastAdapter, IUiValidationAdapter * Enable XML docs + NuGet metadata; include wwwroot for optional CSS shims (spacing/z-index) * Tokens-first: rely on semantic utilities + DaisyUI classes; never hardcode colors

Task COMP-LIB-T70 — DaisyUI Assets & Tailwind Wiring (E2E)

Title: Wire DaisyUI plugin and assets into build

Description: Configure Tailwind to include daisyui plugin for Gallery (and document how consumers do the same). Provide a tiny JS initializer if needed to re-bind behaviors after Blazor renders.

Implementation details:

  • Gallery tailwind.config.cjs: plugins: [require('daisyui')]
  • Document consumer setup (npm add, plugin enable, theme list)
  • Optional JS: daisyui.init.js to re-init on OnAfterRenderAsync if necessary
  • Static web assets: wwwroot/css/daisy-bridge.css for utility shims where DaisyUI lacks density tokens
Task COMP-LIB-T71 — DialogDaisyAdapter (E2E)

Title: Implement DaisyUI dialog adapter using modal patterns

Description: Map IUiDialogAdapter to DaisyUI’s modal structure. Compose header/body/footer with DaisyUI classes, connect action buttons, and integrate focus trap + ESC/overlay handling; respect UiOptions and a11y.

Implementation details:

  • DialogDaisyAdapter : IUiDialogAdapter
  • Render modal container + overlay; map size presets to DaisyUI width utilities
  • Buttons: use DaisyUI button classes (btn, btn-primary, btn-outline, btn-error for destructive)
  • Manage ESC/overlay close; ensure focus trap (our FocusTrap) and announce via LiveRegionService
  • Localize labels via IStringLocalizer; add role="dialog", aria-modal, aria-labelledby/aria-describedby
Task COMP-LIB-T72 — ToastDaisyAdapter + Host (E2E)

Title: Implement DaisyUI toast adapter and host region

Description: Render toasts using DaisyUI toast/alert patterns with stacking, levels (info/success/warning/error), auto-dismiss (pause-on-hover), manual close, and live-region announcements.

Implementation details:

  • ToastDaisyAdapter : IUiToastAdapter
  • Host component DaisyToastHost.razor anchored in layout; default position top-right
  • Level → alert variants (alert-info/success/warning/error) with icons
  • Reduced-motion and high-contrast respected via tokens/attributes
Task COMP-LIB-T73 — ValidationDaisyAdapter (E2E)

Title: Implement DaisyUI validation adapter for field and summary

Description: Show field-level messages and a summary panel using DaisyUI alert and form styles. Integrate with UiValidationService and preserve ARIA relationships to inputs.

Implementation details:

  • ValidationDaisyAdapter : IUiValidationAdapter
  • Field messages under inputs with DaisyUI text/error utilities; link via aria-describedby
  • Summary uses alert with list of errors; optional anchors to first invalid field
  • Density-aware spacing; RTL-safe icons and paddings
Task COMP-LIB-T74 — UiOptions → DaisyUI Bridge (E2E)

Title: Map UiOptions (theme/density/motion/RTL) to DaisyUI themes/classes

Description: Ensure DaisyUI markup responds correctly to our options. Provide mapping and CSS shims where DaisyUI has gaps (notably density).

Implementation details:

  • Theme: map to DaisyUI themes (data-theme="light|dark|...") or consumer-defined themes
  • Density: add .density-compact|cozy|comfortable helpers to adjust paddings/gaps for Daisy components
  • Motion: suppress transitions when reduced motion is set
  • RTL: use logical margins/paddings; verify icons align correctly

Title: Add “DaisyUI” mode to Adapters page with end-to-end demos

Description: Extend Gallery adapters switch to include DaisyUI. Demonstrate dialogs (alert/confirm/prompt), toasts (all levels), and validation on a sample form. Provide copyable DI and Tailwind config snippets.

Implementation details:

  • Switcher: { Null | Bridge | Tokens | Flowbite | DaisyUI }
  • Demos mirror other adapters for side-by-side consistency
  • Setup panel includes:
    • services.AddUiKitAdapters().AddDaisyUiKitAdapters();
    • tailwind.config.cjs DaisyUI plugin snippet
    • Notes on DaisyUI theme selection and RTL/motion caveats
Task COMP-LIB-T76 — Tests & Documentation (E2E)

Title: Add adapter tests and author DaisyUI setup guide

Description: Cover dialog/toast/validation behaviors with DaisyUI implementations; add docs covering installation, Tailwind integration, theme selection, and RTL/motion tips.

Implementation details:

  • Tests:
    • tests/Adapters/DaisyUI/DialogDaisyAdapterTests.cs
    • tests/Adapters/DaisyUI/ToastDaisyAdapterTests.cs
    • tests/Adapters/DaisyUI/ValidationDaisyAdapterTests.cs
    • Verify DI replacement, result paths, ARIA attributes, and live-region calls
  • Docs: docs/adapters-daisyui.md
    • Setup prerequisites (Tailwind + DaisyUI plugin)
    • DI registration, Gallery verification steps
    • UiOptions mapping table and troubleshooting (z-index, density, motion)

Testing Harness

Feature COMP-LIB-F13 — MSTest + bUnit Setup

Goal: Establish a robust test harness for the component library using MSTest + bUnit with helpers for rendering under different themes/cultures/RTL, keyboard simulations, a11y assertions, and stable snapshots. DoD: Tests run via CI with coverage; helper APIs exist for render options, adapters, UiOptions, and culture/RTL; baseline components (Button/TextField/Modal) have smoke + a11y + interaction tests; snapshot pipeline produces stable artifacts.

Task COMP-LIB-T77 — Test Infrastructure & Packages (E2E)

Title: Add MSTest/bUnit/FluentAssertions and baseline test settings

Description: Set up the test project with core packages and default configurations for deterministic test runs, parallelization, and reliable HTML parsing.

Implementation details:

  • Packages: MSTest.TestFramework, MSTest.TestAdapter, bunit, FluentAssertions, AngleSharp (transitive via bUnit), optional Verify.Xunit alternative → prefer MSTest-compatible snapshot tool (Verify.MSTest) if used.
  • Directory.Build.props (tests scope): disable flaky analyzers, set Deterministic=true, turn on LangVersion=latest, InvariantGlobalization=false.
  • runsettings (optional): parallelization, results directory, code coverage collectors (XPlat).
Task COMP-LIB-T78 — TestHost Utilities (Render Options, Adapters, UiOptions)

Title: Implement shared TestHost with render helpers and options

Description: Create a reusable base for tests that configures services, UiOptions, adapters, and rendering settings (theme/density/RTL/HC). Provide extension methods to render components under specific scenarios.

Implementation details:

  • tests/TestHost.cs: wraps Bunit.TestContext, central DI (AddComponentLibrary, AddUiKitAdapters, default Tokens adapter).
  • RenderWithOptions<T>(UiRenderOptions opts) to apply: Theme, Density, Rtl, HighContrast, MotionReduced.
  • WithCulture(string culture) to set CurrentCulture/UICulture.
  • Switch adapters: UseNullAdapters(), UseTokensAdapters(), UseFlowbiteAdapters(), UseDaisyAdapters() guarded by #if TEST_FLOWBITE/DAISY.
  • Normalize output: helper GetNormalizedMarkup() (trim noise attributes/ids for snapshots).
Task COMP-LIB-T79 — Baseline Rendering Smoke Tests

Title: Add smoke tests for Button, TextField, Modal under themes/densities

Description: Ensure core components render without exceptions across light/dark, compact/comfortable, and RTL. Validate essential attributes and classes exist.

Implementation details:

  • tests/Button/ButtonSmokeTests.cs, tests/TextField/TextFieldSmokeTests.cs, tests/Modal/ModalSmokeTests.cs.
  • Matrix: theme {light,dark} × density {compact,comfortable} × {LTR,RTL} (reduced matrix to keep runtime fast).
  • Assertions: no exceptions, root role/aria present (dialog/textbox/button), minimal class presence from tokens.
Task COMP-LIB-T80 — Accessibility Assertions Library

Title: Provide A11yAssert helpers and integrate axe checks in CI

Description: Add lightweight assertion helpers for ARIA roles/labels and wire an axe runner in CI to analyze prerendered gallery pages or component fragments.

Implementation details:

  • tests/Utils/A11yAssert.cs: HasRole, HasAria, IsFocusable, HasLabelledBy, HasDescribedBy.
  • CLI a11y pass (CI stage): run axe or pa11y against static gallery build (or dev server) → store JSON/HTML reports as artifacts; fail on critical violations.
  • In tests, use heuristics (not full axe) for quick ARIA checks to keep unit tests snappy.
Task COMP-LIB-T81 — Keyboard & Focus Simulation

Title: Add key simulation and focus-trap/roving-tabindex tests

Description: Build utilities to simulate Tab/Shift+Tab, Arrow keys, and Esc, then add coverage for Modal focus-trap and future focus-zone/roving-tabindex patterns.

Implementation details:

  • tests/Utils/Keyboard.cs: helpers PressTab(), PressShiftTab(), PressEsc(), PressArrowLeft/Right/Up/Down(), PressHome/End().
  • Modal tests: tab cycles within trap; Esc closes when allowed; overlay click behavior.
  • Prepare base tests for re-use with upcoming menu/list components.
Task COMP-LIB-T82 — Stable Snapshot Testing

Title: Configure HTML snapshot tests with normalization

Description: Introduce snapshot tests for key visual structures (not styling) with deterministic normalization to avoid token/id churn.

Implementation details:

  • Choose snapshot tool for MSTest (e.g., Verify.MSTest).
  • Normalizer strips dynamic ids, whitespace noise, Blazor b- attributes; keeps ARIA, roles, semantic classes.
  • Snapshot cases:
    • Button variants (primary/secondary/danger/subtle × sm/md/lg),
    • TextField (default/required/error),
    • Modal sizes (sm/md/lg).
  • Store snapshots under tests/__snapshots__/… with review docs.
Task COMP-LIB-T83 — CI Wiring, Coverage & Thresholds

Title: Extend pipeline to run tests, publish coverage, gate on failures

Description: Update CI to restore/build/test, publish TRX + coverage, and enforce minimum coverage thresholds for component code and adapters.

Implementation details:

  • Pipeline: dotnet test --collect:"XPlat Code Coverage"; publish coverage (Cobertura) to DevOps/GitHub summary.
  • Thresholds: start modest (e.g., 60% lines/branches), raise in later cycles.
  • Publish artifacts: a11y reports, snapshots, TRX.
  • Optional: flaky-test retry (1x) and test grouping by area.
Task COMP-LIB-T84 — Documentation: Testing Guide

Title: Author docs/testing.md for harness usage and patterns

Description: Document how to write component tests with TestHost, render options, culture/RTL, a11y assertions, keyboard utilities, and snapshots. Provide patterns for adapters and future components.

Implementation details:

  • Sections: Getting started, Render helpers, Culture/RTL, UiOptions, Keyboard sims, A11y assertions, Snapshots, CI tips.
  • Include “gotchas” (async renders, JSInterop fakes, deterministic snapshots) and examples with copy-paste snippets.

Component Test Coverage

Feature COMP-LIB-F14 — Unit Tests for Baseline Components

Goal: Expand unit/integration coverage for Button, TextField, and Modal to validate rendering, parameters, events, accessibility, and keyboard flows across themes/densities/RTL. Ensure stable snapshots for key structures and enforce minimal coverage thresholds for these components. DoD: Tests cover render matrices, events, ARIA/keyboard basics, and error paths; snapshots stored and stable; CI thresholds met (raiseable later).

Task COMP-LIB-T85 — Button: Rendering Matrix & Variants (E2E)

Title: Cover Button rendering across variants/sizes/themes/densities/RTL

Description: Add smoke + snapshot tests ensuring Button renders correctly for {primary, secondary, danger, subtle} × {sm, md, lg} across {light, dark} and {compact, comfortable} plus RTL. Validate ARIA/disabled/loading attributes and icon slots.

Implementation details:

  • Files: tests/Button/ButtonRenderTests.cs, snapshots under tests/__snapshots__/Button/*.
  • Assertions: role/aria present, disabled state blocks click, loading indicator visible when Loading=true, icon-before/after output present.
  • Use RenderWithOptions from TestHost; keep matrix minimal to control runtime.
Task COMP-LIB-T86 — Button: Interaction & Events (E2E)

Title: Validate click/event flows, focus ring, and keyboard activation

Description: Ensure OnClick fires when enabled, not when disabled; Space/Enter activate button; focus ring appears with :focus-visible.

Implementation details:

  • File: tests/Button/ButtonInteractionTests.cs.
  • Simulate mouse click and keyboard (Space/Enter).
  • Assert OnClick not invoked when Disabled=true or Loading=true.
  • Verify focus styles (class presence) after PressTab() and PressShiftTab().
Task COMP-LIB-T87 — TextField: Binding, Validation & ARIA (E2E)

Title: Test controlled/uncontrolled binding, required/invalid states, and aria-linking

Description: Validate Value/ValueChanged flows, Required toggles aria-required, error text sets aria-invalid and creates aria-describedby linkage. Include prefix/suffix slot assertions and RTL caret/align checks.

Implementation details:

  • File: tests/TextField/TextFieldBehaviorTests.cs.
  • Controlled: external value change updates input.
  • Uncontrolled: typing raises ValueChanged.
  • Validation: with EditForm + ValidationMessage<T>, ensure error text renders and links.
  • RTL: render with RTL and assert logical alignment classes applied.
Task COMP-LIB-T88 — Modal: Open/Close, Focus Trap & ESC/Overlay (E2E)

Title: Verify Modal lifecycle, keyboard handling, and ARIA labelling

Description: Test controlled/uncontrolled IsOpen behavior, overlay click to close (toggleable), ESC handling, focus trap cycling with Tab/Shift+Tab, and labelled regions (aria-labelledby/aria-describedby).

Implementation details:

  • File: tests/Modal/ModalInteractionTests.cs.
  • Cases: open then Esc → closes when enabled; overlay click closes when CloseOnOverlay=true; focus starts on initial element; trap prevents escape to background.
  • Snapshot minimal DOM for sizes sm|md|lg.
  • Verify cancellable BeforeCloseAsync blocks close.
Task COMP-LIB-T89 — Cross-Cutting A11y & Keyboard Assertions (E2E)

Title: Add shared a11y checks for baseline components and run axe in CI

Description: Use A11yAssert helpers to verify roles/labels/focusability on Button/TextField/Modal, and run an axe/pa11y pass against prerendered gallery pages to catch regressions (contrast/labels).

Implementation details:

  • File: tests/A11y/BaselineA11yTests.cs.
  • Assert: Button has role, label when icon-only; TextField label linkage; Modal aria-modal and labelled-by/descr-by.
  • CI: run axe/pa11y; publish HTML/JSON reports as artifacts; fail on critical issues.
Task COMP-LIB-T90 — Coverage Thresholds & Docs (E2E)

Title: Enforce minimal coverage and document testing patterns

Description: Set per-project coverage thresholds for components (start 60% lines/branches) and write a short doc explaining how to add tests for new components and keep snapshots stable.

Implementation details:

  • CI: update pipeline to publish Cobertura and enforce thresholds.
  • Docs: docs/testing-baseline-components.md with examples for render/interaction/a11y tests, snapshot normalization guidance, and keyboard helpers usage.

Adapter Test Kit

Feature COMP-LIB-F15 — Conformance Tests for Adapters

Goal: Provide a reusable test kit to validate that any adapter (Tokens, Flowbite, DaisyUI, or custom) conforms to our Dialog/Toast/Validation contracts, keyboard/a11y rules, and UiOptions behaviors. Ensure adapters are swappable via DI and pass the same suite covering focus trap, ESC/overlay close, toast stacking/timers, and validation states/linking. DoD: Shared conformance tests run against all registered adapters; CI executes the full matrix; failures point to clear contract violations; snapshots remain stable.

Task COMP-LIB-T91 — Conformance Harness & Adapters Matrix (E2E)

Title: Build a shared conformance harness and run against all adapters

Description: Create a test base that can spin up the component library with a selected adapter implementation and run a common set of tests (Dialog/Toast/Validation). Include helpers to switch adapters (Tokens/Flowbite/DaisyUI/Null/custom) and re-use identical assertions.

Implementation details:

  • tests/Adapters/Conformance/ConformanceHost.cs:
    • Helper methods: WithTokens(), WithFlowbite(), WithDaisy(), WithNull(), WithCustom(Func<IServiceCollection, IServiceCollection> reg)
    • Expose ArrangeDialog(), ArrangeToastHost(), ArrangeValidationForm() fixtures.
  • Base class AdapterConformanceTestBase used by specific test files.
  • Guard optional kits via compilation symbols (skip if package not referenced).
Task COMP-LIB-T92 — Dialog Conformance: Focus Trap & ESC/Overlay (E2E)

Title: Verify dialog focus trap, ESC/overlay close, ARIA, and results

Description: Ensure each adapter’s dialog satisfies required behaviors: trap focus, close on ESC/overlay when enabled, announce open/close, expose role="dialog" with aria-modal, and return a consistent DialogResult (Alert/Confirm/Prompt/Custom).

Implementation details:

  • tests/Adapters/Conformance/DialogConformanceTests.cs
  • Cases:
    • Focus cycles with Tab/Shift+Tab; initial focus applied.
    • ESC closes when EscToClose=true; overlay click closes when CloseOnOverlay=true.
    • aria-labelledby/aria-describedby correctly wired.
    • AlertAsync, ConfirmAsync, PromptAsync return expected results; prompt returns value.
    • Cancellation: CancellationToken cancels pending dialog.
  • Snapshot minimal DOM for headers/footers per adapter; normalize ids.
Task COMP-LIB-T93 — Toast Conformance: Stacking & Timers (E2E)

Title: Validate toast stacking, levels, auto-dismiss, and a11y announcements

Description: Confirm toast adapters support stacking, correct level mapping (Info/Success/Warning/Error), auto-dismiss with pause-on-hover, manual dismissal, and live-region announcements with the correct politeness.

Implementation details:

  • tests/Adapters/Conformance/ToastConformanceTests.cs
  • Cases:
    • Show 3 toasts → stack order preserved; IDs unique.
    • Auto-dismiss occurs after DurationMs (use deterministic virtual time if possible).
    • Hover pauses timer; leaving resumes; close button focuses and dismisses.
    • Live region announces content; error uses assertive, others polite.
    • DismissAsync(Guid) and ClearAsync() behave correctly.
Task COMP-LIB-T94 — Validation Conformance: Field/Summary States (E2E)

Title: Ensure field errors, summaries, and ARIA linkages are correct

Description: Verify that adapters display field-level messages and summaries, maintain aria-invalid on inputs, and link messages via aria-describedby. Confirm behavior across valid/invalid transitions and with multiple fields.

Implementation details:

  • tests/Adapters/Conformance/ValidationConformanceTests.cs
  • Cases:
    • Required field → error message displayed and linked; clearing value restores valid state.
    • Multiple errors summarized; clicking a summary item focuses the field (if supported).
    • Localization respected (keys appear localized under non-EN cultures).
    • RTL layout doesn’t break message alignment or linking.
Task COMP-LIB-T95 — UiOptions Conformance: Theme/Density/Motion/RTL (E2E)

Title: Test that adapters respect UiOptions for visual/behavioral changes

Description: Assert adapters respond to UiOptions toggles at runtime (light/dark, compact/comfortable, reduced motion, RTL, high-contrast). No hardcoded colors or transitions should leak through when disabled.

Implementation details:

  • tests/Adapters/Conformance/UiOptionsConformanceTests.cs
  • Switch options via UiContextService.SetOptions(...):
    • Theme: structural classes update; dark tokens applied.
    • Density: paddings/sizing adjust in dialogs/toasts/validation blocks.
    • Motion reduced: transitions suppressed (class or media-query check).
    • RTL: layout/order flips correctly; keyboard left/right arrows mirror when applicable.
    • High-contrast: focus rings and contrasts meet thresholds (basic check).
Task COMP-LIB-T96 — CI Matrix & Reporting (E2E)

Title: Run adapter conformance matrix in CI and publish artifacts

Description: Extend the pipeline to execute conformance tests for each available adapter, publish TRX + coverage + a11y artifacts, and surface a human-friendly summary of which adapters passed which checks.

Implementation details:

  • Pipeline matrix stages: Tokens (always), Flowbite/DaisyUI (conditional if packages present).
  • Publish artifacts: TRX, coverage (Cobertura), a11y JSON/HTML report, snapshot diffs.
  • Summary table in job output: rows = adapters, cols = areas (Dialog/Toast/Validation/UiOptions), ✅/❌ marks with links to failing tests.
Task COMP-LIB-T97 — Documentation: Adapter Conformance Guide

Title: Document how to validate a custom adapter with the kit

Description: Provide a guide that explains how to run the conformance suite locally for custom adapters, what the required behaviors are, and how to interpret/resolve failures.

Implementation details:

  • docs/adapter-conformance.md
  • Sections: How to plug your adapter into tests, Required behaviors, A11y/keyboard checklist, UiOptions mapping, CI integration tips.
  • Include a minimal custom adapter example + test bootstrap snippet.

Goal: Deliver a polished Gallery application that demonstrates all baseline components (Button, TextField, Modal, etc.) across states, themes, densities, and adapter modes. Provide an interactive switcher for theme/density/RTL/motion and adapters (Tokens/Flowbite/DaisyUI), enabling developers to preview and copy snippets directly. DoD: Gallery runs as a Blazor Server app; each component has a dedicated demo page; global controls adjust options live; demos display localized text; snippets are shown inline.

Title: Scaffold Gallery Blazor Server project

Description: Create a new Blazor Server project for the Gallery, wire it to the component library, and configure Tailwind + tokens. Provide a minimal layout with navigation sidebar and top bar.

Implementation details:

  • Project: samples/ConnectSoft.Blazor.ComponentLibrary.Gallery/
  • Layout:
    • Sidebar: navigation to component demo pages (Button, TextField, Modal, Adapters, Accessibility, etc.)
    • Top bar: brand, Settings toggle, GitHub/Docs links
  • Add Tailwind pipeline + token CSS static assets (reuse from RCL)
  • Reference ConnectSoft.Blazor.ComponentLibrary and adapter packages
Task COMP-LIB-T99 — Global Settings Switcher (E2E)

Title: Implement theme/density/RTL/motion toggle panel

Description: Add a global settings panel in Gallery that manipulates UiOptions and re-renders components accordingly. Persist selections in localStorage.

Implementation details:

  • Options: Theme (light/dark), Density (compact/cozy/comfortable), Motion (full/reduced), RTL (on/off), High-Contrast (on/off)
  • Store via IJSRuntime localStorage; restore on load
  • Update root <html> with data-* attributes and dir="rtl"
  • Settings panel accessible from top bar
Task COMP-LIB-T100 — Component Demo Pages (E2E)

Title: Add dedicated pages for Button, TextField, and Modal demos

Description: Provide interactive demos for baseline components, showcasing all variants, states, and localized text. Include copyable Razor snippets.

Implementation details:

  • Pages/ButtonDemo.razor: grid of variants (primary/secondary/danger/subtle × sizes), disabled/loading states, icon examples
  • Pages/TextFieldDemo.razor: default, required, helper text, error text, prefix/suffix icons, RTL examples
  • Pages/ModalDemo.razor: alert, confirm, prompt, form-in-modal, long scroll content, size presets
  • Snippet component: display <pre><code> Razor markup with copy-to-clipboard button
Task COMP-LIB-T101 — Adapter Demos Page (E2E)

Title: Add Adapters demo page with switchable modes

Description: Show Dialog, Toast, and Validation flows under different adapter implementations (Null, Tokens, Flowbite, DaisyUI). Allow runtime switching.

Implementation details:

  • Pages/AdaptersDemo.razor
  • Dropdown: { Null | Tokens | Flowbite | DaisyUI }
  • Demos:
    • Dialog: Alert/Confirm/Prompt
    • Toast: Info/Success/Warning/Error
    • Validation: simple form with required + error summary
  • Show DI snippet for registering chosen adapter
Task COMP-LIB-T102 — Accessibility & i18n Demo Page (E2E)

Title: Showcase accessibility utilities and localization

Description: Provide a dedicated page for FocusTrap, RovingTabIndex, LiveRegion, and localized text across EN/RU/HE. Include RTL toggle.

Implementation details:

  • Pages/AccessibilityDemo.razor:
    • FocusTrap demo modal
    • RovingTabIndex toolbar
    • FocusZone grid navigation
    • LiveRegion polite/assertive announcements
  • Pages/LocalizationDemo.razor:
    • Dropdown to switch between EN/RU/HE
    • Render Button/TextField/Modal with localized strings
    • RTL toggle for Hebrew
Task COMP-LIB-T103 — Docs & Navigation Integration (E2E)

Title: Add documentation links and navigation polish

Description: Link Gallery pages to relevant docs in docs/ (usage, adapters, options). Provide “View Docs” buttons per component demo. Ensure sidebar navigation is consistent and collapsible.

Implementation details:

  • Sidebar grouping: “Components”, “Adapters”, “Accessibility”, “Localization”, “Settings”
  • Each page has “View Docs” button linking to MkDocs pages (docs/*.md)
  • Ensure responsive layout (sidebar collapses on mobile)

Title: Add bUnit/Playwright smoke tests for Gallery pages

Description: Cover navigation between pages, global settings persistence, and basic rendering of demos. Add Playwright e2e flow to validate adapter switch, theme/density toggles, and localization.

Implementation details:

  • tests/Gallery/GallerySmokeTests.cs:
    • Render each page; assert key headings/snippets present
  • Playwright test flow (if added):
    • Visit /button, toggle theme/density, switch adapters, change language, assert DOM updates
  • CI: build Gallery, run unit + Playwright tests, publish coverage + screenshots

Documentation

Feature COMP-LIB-F17 — Docs & ADRs

Goal: Establish high-quality developer documentation for the component library, including README, usage guides, MkDocs site, and ADRs for major design decisions. Ensure documentation is consistent, easy to navigate, and integrated into CI/CD. DoD: Top-level README published, guides available for setup/usage/adapters/options, MkDocs site runs locally and deploys via pipeline, ADRs captured under /docs/adr/.

Task COMP-LIB-T105 — Top-Level README (E2E)

Title: Author repository README with quickstart and links

Description: Write a comprehensive README.md that introduces the component library, shows install/setup steps, and links to docs and Gallery.

Implementation details:

  • Sections: Overview, Features, Quickstart (dotnet new template), Usage snippet, Contributing, License
  • Add badges: build status, coverage, NuGet
  • Link to Gallery app and MkDocs site once deployed
  • Keep concise but developer-focused
Task COMP-LIB-T106 — Usage Guides (E2E)

Title: Create usage documentation for components, options, adapters

Description: Add guides under /docs/ explaining how to consume the library, configure options, and register adapters.

Implementation details:

  • docs/getting-started.md — install, configure services, add UiContext
  • docs/components.md — examples for Button/TextField/Modal with Razor snippets
  • docs/options.md — configuring UiOptions (appsettings + runtime overrides)
  • docs/adapters.md — overview of adapter contracts and available packages (Tokens, Flowbite, DaisyUI)
  • docs/testing.md — writing component tests with bUnit + TestHost utilities
  • Each file includes code blocks and screenshots (from Gallery)
Task COMP-LIB-T107 — MkDocs Site Integration (E2E)

Title: Set up MkDocs with Material theme for documentation site

Description: Configure MkDocs to serve /docs/ with navigation, search, and theming. Add pipeline integration to publish docs as static site (Azure Static Web Apps or GitHub Pages).

Implementation details:

  • mkdocs.yml: site name, repo links, navigation tree, theme (Material)
  • Add plugins: search, awesome-pages, ADR viewer (if available)
  • Configure CI pipeline step to build docs (mkdocs build) and deploy to target host
  • Add docs/index.md landing page with overview, links, and badges
Task COMP-LIB-T108 — ADR Structure & Initial Records (E2E)

Title: Create architecture decision record folder and first ADRs

Description: Establish /docs/adr/ with log4brains-compatible format for tracking design decisions. Write initial ADRs for design tokens, adapters, and options system.

Implementation details:

  • Setup: docs/adr/0000-use-log4brains.md to define format/tooling
  • ADRs:
    • 0001-use-design-tokens-for-styling.md
    • 0002-adapter-contracts-for-ui-kits.md
    • 0003-uioptions-for-global-config.md
  • Document alternatives considered, pros/cons, and final decision
  • CI step: validate ADRs build with log4brains build (optional)

Title: Add cross-links between Gallery demos and docs pages

Description: Ensure every Gallery page links to its relevant doc page and docs link back to Gallery demos.

Implementation details:

  • In Gallery pages (ButtonDemo, ModalDemo, etc.), add “View Docs” button linking to MkDocs page
  • In docs pages, add “Open Demo in Gallery” link to /gallery/...
  • Test links locally with MkDocs + Gallery running side by side
Task COMP-LIB-T110 — CI/CD Documentation Pipeline (E2E)

Title: Extend CI to validate docs, lint markdown, and deploy site

Description: Add CI jobs to lint markdown/links, build docs, and deploy to hosting environment.

Implementation details:

  • Install markdownlint or remark-lint for style checks
  • Step: mkdocs build → verify build passes
  • Deployment:
    • Azure Static Web Apps (preferred)
    • or GitHub Pages fallback
  • Publish logs + site URL in build summary

Quality Gates

Feature COMP-LIB-F18 — CI/CD Rules

Goal: Enforce consistent quality by adding automated checks to the pipeline: token drift detection, accessibility scanning, and analyzer pack integration with fail-on-error gates. Extend with coverage thresholds, artifact publishing, and PR protection so regressions are caught early. DoD: CI fails on raw color usage, a11y violations, or analyzer errors; coverage and snapshots published; PRs blocked until gates pass.

Task COMP-LIB-T111 — Token Drift Detector (E2E)

Title: Add no-raw-color/token-drift check to CI

Description: Prevent accidental hard-coded colors and style drift by failing the build when hex/RGB/HSL values appear in component code or Razor/CSS (outside approved token files).

Implementation details:

  • Script build/tools/token-drift-check.(ps1|sh) scans src/ for #([0-9a-f]{3}|[0-9a-f]{6})\b|rgb\(|hsl\( excluding wwwroot/css/tokens*.css.
  • Add allowlist file build/tools/token-drift-allow.txt for rare exceptions.
  • Wire into CI before tests; fail with a readable diff of offending lines.
  • Document rule in docs/contributing.md.
Task COMP-LIB-T112 — Accessibility Scan in Pipeline (E2E)

Title: Run automated a11y scanner against Gallery and fail on violations

Description: Execute an accessibility scan (axe/pa11y) over key Gallery routes (components, adapters, a11y/i18n pages) and fail on critical issues (contrast, missing labels, invalid roles).

Implementation details:

  • Build Gallery in CI; start a local server or prerender pages.
  • Run pa11y-ci/axe via config listing routes (/button, /textfield, /modal, /adapters, /accessibility, /localization).
  • Output HTML/JSON reports to artifacts/a11y/ and publish.
  • Treat “serious/critical” as errors; “moderate/minor” as warnings (non-blocking).
Task COMP-LIB-T113 — Analyzer Pack & Warnings-as-Errors (E2E)

Title: Integrate Roslyn analyzers and enforce WAE in library + adapters

Description: Add a curated analyzer pack and turn on warnings as errors to prevent code smells. Provide solution-level ruleset and suppression file for vetted cases.

Implementation details:

  • Add analyzer packages (e.g., Microsoft.CodeAnalysis.NetAnalyzers, IDisposableAnalyzers, optional style rules).
  • build/Directory.Build.props: <TreatWarningsAsErrors>true> (library/adapters); tests may relax.
  • Add build/.editorconfig with severity map; GlobalSuppressions.cs only for justified exceptions.
  • CI step prints analyzer summary with quick links to docs.
Task COMP-LIB-T114 — Coverage Thresholds & Artifacts (E2E)

Title: Enforce minimum coverage and publish results/badges

Description: Require a baseline coverage (e.g., 60% lines/branches) and publish Cobertura/HTML reports as artifacts; output a badge URL for README.

Implementation details:

  • dotnet test --collect:"XPlat Code Coverage" → convert to Cobertura/HTML.
  • Coverage gate task compares metrics to thresholds; fails on regressions.
  • Publish to CI summary and artifacts/coverage/; add README badge snippet.
Task COMP-LIB-T115 — Snapshot Stability & Diff Reporting (E2E)

Title: Stabilize snapshot tests and surface readable diffs in CI

Description: Ensure deterministic snapshots and human-friendly diffs for failures to reduce flakiness.

Implementation details:

  • Normalize markup (strip transient ids/attributes) in snapshot helper.
  • On failure, upload “expected vs actual” HTML to artifacts/snapshots/.
  • CI summary links per failing test with a compact diff.
Task COMP-LIB-T116 — PR Gates & Branch Protection (E2E)

Title: Lock master/main with required checks and status reporting

Description: Configure PR checks so merges require token-drift, analyzers, a11y, tests, and coverage gates to pass; block direct pushes to main.

Implementation details:

  • Enable required status checks: build, test, coverage, a11y, analyzers, token-drift.
  • Require reviews and disallow bypass except for admins.
  • Add CODEOWNERS for critical folders (library, adapters, tokens).
  • Document the PR flow in docs/engineering-standards.md.

Packaging & Distribution

Feature COMP-LIB-F19 — NuGet Packaging

Goal: Ship the component library and optional adapters as high-quality NuGet packages with static web assets, SourceLink, symbols, and a dotnet new template (template.json). Establish deterministic builds, semantic versioning, and publish pipelines (CI/CD) with validations. DoD: ConnectSoft.Blazor.ComponentLibrary packs with static web assets; PDB + SourceLink available; symbols published; template.json installs and generates a runnable scaffold; pipeline publishes to Azure Artifacts/NuGet on tagged releases.

Task COMP-LIB-T117 — Packaging Props & Deterministic Build (E2E)

Title: Create shared packaging props/targets for all ship-ready projects

Description: Introduce solution-wide packaging settings to guarantee deterministic builds, SourceLink, and proper metadata across the library and adapters.

Implementation details:

  • build/Directory.Build.props (shipping scope):
    • <ContinuousIntegrationBuild>true>, <Deterministic>true>, <EmbedUntrackedSources>true>
    • <PublishRepositoryUrl>true>, <RepositoryType>git</RepositoryType>, <RepositoryUrl>...</RepositoryUrl>
    • <IncludeSymbols>true>, <SymbolPackageFormat>snupkg</SymbolPackageFormat>
    • <GenerateDocumentationFile>true>
  • Add Microsoft.SourceLink.GitHub (or Azure DevOps variant) package.
  • Set common NuGet metadata: Authors, PackageProjectUrl, PackageReadmeFile, PackageTags.
  • Verify dotnet pack -c Release produces deterministic .nupkg + .snupkg.
Task COMP-LIB-T118 — Static Web Assets & Content Inclusion (E2E)

Title: Ensure static web assets (CSS/tokens) are packed and discoverable

Description: Configure the RCL and adapter projects to include all CSS/asset files under wwwroot and validate consumption from a downstream app via UseStaticWebAssets.

Implementation details:

  • Confirm RazorLangVersion, RazorSdk defaults; ensure wwwroot/**/* included.
  • Add Content/None includes only if custom globs required (avoid duplicates).
  • Verify consuming sample app loads token CSS and adapter CSS via _content/{PackageId}/....
  • Playwright/bUnit smoke test in the samples to prove discovery works after pack + add package.
Task COMP-LIB-T119 — Template Packaging (template.json) (E2E)

Title: Pack dotnet new template with sane symbols and post-actions

Description: Finalize the template project so dotnet new install yields a runnable solution (library + tests + gallery) with customizable names and safe defaults.

Implementation details:

  • template/.template.config/template.json:
    • identity, shortName (e.g., cs-blazor-comp-lib), classifications, sourceName
    • symbols for Company, LibraryName, UseAdapters (bools/enums)
    • postActions: run dotnet restore and hint on npm install for Tailwind if desired
  • dotnet new install ./template → dotnet new cs-blazor-comp-lib -n DemoOrg.DemoLib should build + run Gallery.
  • Add README-template.md consumed as README.md in generated repo.
Task COMP-LIB-T120 — Versioning & Release Workflow (E2E)

Title: Implement semver tagging and release artifact generation

Description: Adopt Git tag–driven semantic versioning and generate signed release artifacts with changelogs.

Implementation details:

  • Choose scheme: v{major}.{minor}.{patch} tags → pipeline sets VersionPrefix.
  • Optional: GitVersion or lightweight script to compute prerelease labels (-beta.1).
  • Generate CHANGELOG.md entries from conventional commits or PR titles.
  • Attach packages (.nupkg, .snupkg) to release; publish build summary with package IDs/versions.
Task COMP-LIB-T121 — Publish Pipelines (E2E)

Title: Add CI/CD stages to push to Azure Artifacts and NuGet.org

Description: Create secure pipelines that push packages on signed/tagged releases, with API keys/feeds stored in secret variables.

Implementation details:

  • CI: build, test, quality gates.
  • CD (on tag):
    • dotnet pack -c Release
    • dotnet nuget push **/*.nupkg --source "AzureArtifacts"
    • Conditional second push to nuget.org when Release tag and approval gate passes.
  • Publish symbols (.snupkg) to matching symbol source.
  • Gate: fail if tests/gates didn’t pass or version already exists.
Task COMP-LIB-T122 — Package Validation & Smoke Install (E2E)

Title: Validate produced packages by installing into a clean sample app

Description: After packing, spin up a clean test app that references the newly built packages to ensure static web assets, adapters, and template install all function end-to-end.

Implementation details:

  • Pipeline job: create temp workspace → dotnet new blazorserver -n PkgSmoke
  • dotnet add PkgSmoke package ConnectSoft.Blazor.ComponentLibrary -s ./artifacts/packages
  • Run app: assert CSS served from _content/...; render Button/Modal; show Toast.
  • Template: dotnet new install <artifact.nupkg> (template) → generate → build & run Gallery.
  • Upload screenshots/logs as artifacts; fail on any smoke error.

Release & Catalog Registration

Feature COMP-LIB-F20 — Catalog & Release Integration

Goal: Finalize release flow by publishing packages to Azure Artifacts, syncing a public Catalog manifest so consumers can discover the template and components, and attaching structured Release Notes. Automate the update of docs badges, changelog, and gallery links on each tagged release. DoD: Tagged release publishes NuGet packages to Azure Artifacts (and optional NuGet.org per policy), opens/merges a PR updating the Catalog manifest, and attaches release notes + changelog. Docs and README badges reflect the new version.

Task COMP-LIB-T123 — Catalog Manifest & Badges (E2E)

Title: Define Catalog manifest schema and add repo status badges

Description: Create/align a machine-readable catalog entry describing the Component Library, adapters, and template. Add badges (build, coverage, latest version) to README and docs.

Implementation details:

  • catalog/manifest.json (or external catalog repo):
    • id, name, description, packages (library + adapters + template), latestVersion, docsUrl, galleryUrl, sourceUrl
    • Optional: tags, supportedFrameworks, license
  • README: add “Latest Version” badge sourced from Azure Artifacts feed; link to Gallery + Docs.
  • MkDocs footer: version + build datetime.
Task COMP-LIB-T124 — Release Pipeline Orchestration (E2E)

Title: Extend CI/CD to run release job on Git tag and gate with approvals

Description: Wire a dedicated pipeline stage triggered by v*.*.* tags that runs packing, validation, publishing, catalog sync, and notes generation with manual approval gate if required.

Implementation details:

  • Stages: build → test → quality-gates → pack → publish → catalog-sync → release-notes.
  • Manual approver list for publish (if policy dictates).
  • Cache artifacts between stages; fail-fast on gates.
Task COMP-LIB-T125 — Publish to Azure Artifacts (E2E)

Title: Push packages and symbols to Azure Artifacts feed with retention

Description: Configure secure publish to Azure Artifacts, including .snupkg symbols, and set retention/promotion rules.

Implementation details:

  • Secrets: feed URL + API key/connection via secure variables.
  • Command: dotnet nuget push **/*.nupkg --source "<ArtifactsFeed>" --skip-duplicate.
  • Symbols: push .snupkg to symbol feed (if separate).
  • Retention: keep pre-releases 6 months; LTS releases indefinite.
Task COMP-LIB-T126 — Catalog Sync Automation (E2E)

Title: Open PR to Catalog repo updating manifest/version and links

Description: After publish, auto-bump latestVersion and package entries in Catalog (same repo or external). Create a PR with changelog excerpt.

Implementation details:

  • Script updates catalog/manifest.json with new version(s) + timestamps.
  • If catalog is external: use GitHub/Azure DevOps API to open PR from bot user.
  • Include release summary (highlights, breaking changes) in PR description.
  • Pipeline waits for PR merge (optional) or posts link in job summary.
Task COMP-LIB-T127 — Release Notes & Changelog (E2E)

Title: Generate structured release notes and append to CHANGELOG.md

Description: Compose release notes from conventional commits/PR titles grouped by Features/Fixes/Docs/Breaking. Attach to GitHub/Azure release and update CHANGELOG.md.

Implementation details:

  • Tool/script aggregates commits since previous tag.
  • Create Release with tag vX.Y.Z, title, notes body; attach .nupkg links and docs site URL.
  • Append to CHANGELOG.md and push back to main (or open auto-PR).
Task COMP-LIB-T128 — Template & Docs Version Pinning (E2E)

Title: Bump template defaults and docs snippets to latest version

Description: Ensure the dotnet new template and documentation reference the newly released versions (library, adapters) so new consumers get the correct packages.

Implementation details:

  • Update template/content/**/csproj package versions via script during release.
  • Search/replace in docs/*.md code blocks for version pins; regenerate MkDocs.
  • Validate dotnet new install produces a project that restores with the released versions.
Task COMP-LIB-T129 — Post-Release Verification (E2E)

Title: Smoke-install from feed and run minimal e2e checks

Description: In a clean workspace, consume the just-published packages from Azure Artifacts and verify static web assets and adapters function.

Implementation details:

  • dotnet new blazorserver -n ReleaseSmoke → add package refs from the feed.
  • Render Button/Modal/Toast; assert _content/{PackageId}/ assets load (simple HTTP check).
  • Capture screenshots/logs and publish as artifacts; fail stage on errors.
Task COMP-LIB-T130 — Communication & Support Hooks (E2E)

Title: Announce release and surface support links in docs/site

Description: Post an announcement (Teams/Slack/Email) with highlights and upgrade notes; add “Report an issue” and “Discussions” links in docs and Gallery footer.

Implementation details:

  • Pipeline step posts message with changelog highlights + install snippet.
  • Docs/Gallery footer: links to Issue tracker, Discussions, Security policy.
  • Add SUPPORT.md with triage expectations and SLA (if applicable).

Feature — Advanced Form Components

Goal: Deliver token-driven, accessible form inputs beyond TextField: Select/Dropdown, Checkbox/Radio groups, DatePicker, TextArea, plus a FormLayout helper. All controls support controlled/uncontrolled patterns, validation with EditForm, localization/RTL, and keyboard navigation. DoD: Components render and validate within EditForm; i18n/RTL/UiOptions respected; gallery pages with copyable snippets; unit + a11y tests added.

Task COMP-LIB-T131 — Select/Dropdown (E2E)

Title: Implement token-driven Select/Dropdown with keyboard navigation

Description: Create <Select> with single/multi select, search (optional), and full keyboard support (open/close, typeahead, arrows, Home/End, Enter/Space, Esc). Integrate with EditForm and adapters where needed.

Implementation details:

  • Files: src/Components/Select/Select.razor (+ .razor.css), Option.razor.
  • Parameters: IEnumerable<TItem> Items, RenderFragment<TItem> ItemTemplate, TItem? Value, EventCallback<TItem?> ValueChanged, IEnumerable<TItem>? Values, EventCallback<IEnumerable<TItem>?> ValuesChanged, bool Multi, bool Searchable, string? Placeholder, bool Disabled.
  • Accessibility: role="combobox", aria-expanded, aria-controls, active option with aria-activedescendant; listbox role="listbox", options role="option".
  • Keyboard: ArrowUp/Down navigate; Enter/Space select; Esc closes; typeahead buffer for quick jump.
  • Styling: semantic tokens for surface/content/selection/focus rings; density tokens for item height.
  • Validation: aria-invalid, aria-describedby with error id; integrates with EditContext.
  • RTL: mirror chevrons and key behavior for Left/Right in grids.
  • Gallery: page with single, multi, disabled, searchable, long lists, async load demo.
Task COMP-LIB-T132 — Checkbox & Radio Groups (E2E)

Title: Implement grouped Checkbox/Radio with roving tabindex and legends

Description: Build Checkbox and Radio plus CheckboxGroup/RadioGroup supporting labels, helper/error text, validation, and roving tabindex for arrow-key navigation within the group.

Implementation details:

  • Files: src/Components/Checkbox/*.razor, src/Components/Radio/*.razor.
  • Parameters:
    • Checkbox: bool Checked, EventCallback<bool> CheckedChanged, string? Label, string? HelperText, bool Disabled.
    • RadioGroup: T? Value, EventCallback<T?> ValueChanged, IEnumerable<RadioOption<T>> Options, string? Legend.
  • Accessibility: fieldset/legend for groups; inputs with associated labels; radios use roving tabindex; aria-invalid and described-by when invalid.
  • Tokens: focus ring, selection state, hover, disabled; density for spacing/size.
  • Validation: integrates with EditForm; group-level errors rendered near legend.
  • Gallery: grids for checkbox states; radio group with keyboard demo; RTL examples.
Task COMP-LIB-T133 — DatePicker (E2E)

Title: Implement accessible DatePicker with keyboard grid and i18n

Description: Create a date picker using a popover calendar grid (no hardcoded colors), fully keyboard-accessible and localized (month/day names, first-day-of-week). Provide min/max, disabled dates, and custom day render.

Implementation details:

  • Files: src/Components/DatePicker/DatePicker.razor (+ .razor.css).
  • Parameters: DateOnly? Value, EventCallback<DateOnly?> ValueChanged, DateOnly? Min, DateOnly? Max, Func<DateOnly, bool>? IsDateDisabled, RenderFragment<DayContext>? DayTemplate, bool ShowTodayButton.
  • Accessibility: button opens calendar (aria-haspopup="dialog"); calendar role="grid", days role="gridcell", current day aria-current="date", selected aria-selected="true".
  • Keyboard: Arrow keys move day, PgUp/PgDn change month, Home/End jump to week ends, Enter selects, Esc closes.
  • i18n: month/day names from culture; week start from CultureInfo; date formatting localized.
  • RTL: grid navigation mirrors Left/Right; arrows flipped.
  • Tokens: surfaces/elevations for popover; focus ring on active cell; density affects cell size.
  • Gallery: min/max demo, disabled weekends, custom DayTemplate with badges.
Task COMP-LIB-T134 — TextArea (E2E)

Title: Implement TextArea with character counter and auto-resize

Description: Build TextArea with optional MaxLength displaying a counter, soft/hard limit modes, and auto-resize (respecting reduced motion). Integrate with EditForm validation.

Implementation details:

  • Files: src/Components/TextArea/TextArea.razor (+ .razor.css).
  • Parameters: string? Value, EventCallback<string?> ValueChanged, int? MaxLength, bool EnforceMaxLength, int Rows = 3, bool AutoResize = true, string? Label, string? HelperText, string? ErrorText, bool Disabled, bool Required.
  • Accessibility: label/id linkage; aria-required, aria-invalid, counter announces remaining chars via aria-live="polite".
  • Tokens: border/content/focus; density for padding/line-height.
  • Auto-resize: measure scroll height; disable smooth transitions when Motion reduced.
  • Gallery: with/without counter, error state, RTL layout, long content.
Task COMP-LIB-T135 — FormLayout Helper (E2E)

Title: Provide FormLayout with rows/columns, labels, and summary

Description: Create FormLayout primitives to standardize spacing, label alignment, and validation summary placement across forms.

Implementation details:

  • Files: src/Components/FormLayout/FormLayout.razor, FormRow.razor, ValidationSummary.razor.
  • Features: horizontal/vertical layouts, responsive columns, aligned label column, slot for actions.
  • Integrates with UiValidationService for summary display; tokenized spacing and dividers; density scaling.
  • Gallery: complex form demo mixing Select, DatePicker, TextField, TextArea, with summary at top.

Title: Add demos for Select, Checkbox/Radio, DatePicker, TextArea, and FormLayout

Description: Create dedicated Gallery pages with interactive states, adapters switch, and copy-to-clipboard snippets for each control.

Implementation details:

  • Pages: SelectDemo.razor, ChoiceGroupDemo.razor, DatePickerDemo.razor, TextAreaDemo.razor, FormLayoutDemo.razor.
  • Show theme/density/RTL toggles; include localized labels (EN/RU/HE).
  • Provide minimal + advanced examples (e.g., async Select loading).
Task COMP-LIB-T137 — Tests & A11y (E2E)

Title: Add unit/a11y tests for new form controls and layout

Description: Cover rendering, binding, keyboard behavior, ARIA, and validation. Include snapshot tests for stable structures and axe scans for pages.

Implementation details:

  • SelectTests: open/close, typeahead, single/multi select, ARIA combobox/listbox, RTL keys.
  • ChoiceGroupTests: roving tabindex, legend/fieldset semantics, validation state.
  • DatePickerTests: grid navigation, min/max, disabled dates, localized month/day names.
  • TextAreaTests: counter behavior, auto-resize toggle, validation ARIA.
  • FormLayoutTests: label alignment, summary linkage to fields.
Task COMP-LIB-T138 — Documentation & Migration Notes (E2E)

Title: Author docs for advanced form components and patterns

Description: Add pages explaining API, validation patterns, keyboard maps, and customization, with links to Gallery demos.

Implementation details:

  • docs/components-select.md, components-choice-group.md, components-datepicker.md, components-textarea.md, components-formlayout.md.
  • Sections: Usage, Parameters, Accessibility, Validation, RTL/i18n, Theming, Snippets, Gotchas.
  • Include decision notes if any trade-offs (e.g., virtualized long lists for Select).

Feature — COMP-LIB-F22 — Data Display Components

Goal: Provide token-driven, accessible data display primitives: a flexible Table/Grid (with paging and sorting hooks), Badge/Tag/Chip status indicators, and Avatar/UserCard building blocks. Ensure great performance (virtualization-ready), theming/RTL support, and clean APIs that integrate with adapters and validation where relevant. DoD: Table/Grid renders large datasets with paging and sorting hooks; Badge/Tag/Chip map statuses to tokens; Avatar/UserCard render consistently across densities; gallery pages and docs exist; tests cover interaction, a11y, and RTL.

Task COMP-LIB-T139 — Table/Grid Core (E2E)

Title: Implement token-driven Table/Grid with column/row templates and empty/ loading states

Description: Create a lightweight, extensible Table/Grid component with slots for header, rows, cells, and footer. Support client-side paging, column alignment, sticky header, and empty/loading placeholders.

Implementation details:

  • Files: src/Components/Data/TableGrid.razor, TableGrid.razor.css, Column<T>.cs
  • Parameters: IReadOnlyList<T> Items, RenderFragment<T> RowTemplate, RenderFragment? EmptyTemplate, RenderFragment? LoadingTemplate, IReadOnlyList<Column<T>> Columns, int PageSize, int PageIndex, EventCallback<int> PageIndexChanged, bool StickyHeader
  • Tokens-first classes for surface, borders, zebra stripes (optional), focus states for row selection
  • Density-aware row height and padding; RTL-safe column alignment
  • Keyboard: arrow navigation across cells (optional), focus outline on selected row
  • Gallery: show large list (1–5k items) with paging; empty and loading demos
Task COMP-LIB-T140 — Sorting & Data Hooks (E2E)

Title: Add sorting hooks, sort indicators, and data adapter shape

Description: Provide a sorting contract (client/server) with events and visual indicators; expose a data adapter interface to plug remote data (server paging/sorting).

Implementation details:

  • API: SortDescriptor { string Field; SortDirection Direction }, event OnSortChanged
  • Visuals: tokenized sort chevrons; ARIA aria-sort="ascending|descending|none" on header cells
  • Data adapter interface: IDataSource<T> with Task<DataPage<T>> QueryAsync(DataQuery q, CancellationToken) supporting paging + sorting (+ future filter)
  • Gallery: client-side sorting with 3 columns; server-mode demo with mock datasource
Task COMP-LIB-T141 — Badges/Tags/Chips (E2E)

Title: Implement Badge, Tag, and Chip with status → token mapping and dismiss/action slots

Description: Build small display primitives for status and categorization, mapping semantic statuses to tokens. Support optional icons, dismiss buttons, and on-click actions.

Implementation details:

  • Components: Badge, Tag, Chip in src/Components/Data/Indicators/*
  • Props: Status enum (Info|Success|Warning|Error|Neutral), Icon, OnDismiss, OnClick, Size (sm|md), Outline variant
  • Tokens: background/foreground/elevation per status; focus ring on interactive Chips
  • A11y: role="status" for passive; button semantics for interactive; proper aria-label on dismiss
  • Gallery: grid of variants; dense vs comfortable comparison; RTL examples
Task COMP-LIB-T142 — Avatar & UserCard (E2E)

Title: Implement Avatar (initials/image/fallback) and UserCard (media + meta + actions)

Description: Create avatars with image/initials and fallback color from tokens; compose a UserCard that uses Avatar + text/content slots and optional actions (e.g., buttons, menu).

Implementation details:

  • Components: Avatar.razor, UserCard.razor
  • Avatar props: string? Name, string? ImageUrl, Size (xs|sm|md|lg), Shape (circle|rounded), StatusDot (online|away|busy|offline|none)
  • Fallback: initials from name; token-derived background; accessible alt/aria-label
  • UserCard slots: Header, Body, Footer; tokens for spacing and elevation; density-aware layout
  • Gallery: avatars with/without images, different sizes; cards with actions and long text

Title: Add demos for Table/Grid, Indicators, and UserCard with copyable snippets

Description: Create dedicated Gallery pages showcasing Table/Grid (paging/sorting), Badge/Tag/Chip, and Avatar/UserCard with theme/density/RTL switches and DI snippets when needed.

Implementation details:

  • Pages: TableGridDemo.razor, IndicatorsDemo.razor, UserCardDemo.razor
  • Include code snippets (copy-to-clipboard), and performance note for large lists
  • Provide adapter-mode note for future styling kits (Flowbite/DaisyUI) compatibility
Task COMP-LIB-T144 — Tests & A11y (E2E)

Title: Add unit/a11y tests for data display components and interactions

Description: Cover Table/Grid rendering, paging & sort events, ARIA attributes; Badge/Tag/Chip status mapping and dismiss actions; Avatar alt/initials fallback and UserCard structure.

Implementation details:

  • TableGridTests: header roles (columnheader), aria-sort, paging change raises PageIndexChanged, sort event emits descriptor, sticky header class present
  • IndicatorsTests: status maps to classes; chip dismiss invokes callback; keyboard activation works
  • AvatarUserCardTests: initials computed; alt present; card regions render; RTL snapshot
  • Add axe/pa11y checks for demos in CI
Task COMP-LIB-T145 — Documentation (E2E)

Title: Author docs for Table/Grid, Indicators, and UserCard patterns

Description: Provide usage, parameters, accessibility notes, and customization via tokens, including server-data guidance for Table/Grid.

Implementation details:

  • Docs: docs/components-table-grid.md, docs/components-indicators.md, docs/components-usercard.md
  • Sections: Usage, Parameters, Accessibility, Theming/RTL, Performance (virtualization/server mode), Snippets, Gotchas
  • Cross-link to Gallery demos and adapter styling guidance

Feature — COMP-LIB-F23 — Navigation Components

Goal: Provide token-driven, accessible navigation primitives: Tabs, Accordion, and Breadcrumbs, each supporting keyboard navigation, RTL, theming/density, and optional adapter integration. Ensure components compose well with existing primitives (FocusZone/RovingTabIndex, LiveRegion, UiOptions), and ship with demos, tests, and docs. DoD: Tabs, Accordion, and Breadcrumbs render with tokens; keyboard maps validated; RTL/i18n respected; Gallery pages with copyable snippets; unit + a11y tests pass; optional bridges for adapters ready.

Task COMP-LIB-T146 — Tabs (E2E)

Title: Implement token-driven Tabs with FocusZone + RovingTabIndex

Description: Create Tabs with TabList, Tab, and TabPanel. Support controlled/uncontrolled active tab, keyboard navigation (Left/Right or Up/Down depending on orientation), Home/End jump, and appropriate ARIA linkage.

Implementation details:

  • Files: src/Components/Navigation/Tabs/*.razor (Tabs.razor, TabList.razor, Tab.razor, TabPanel.razor).
  • Parameters: int ActiveIndex, EventCallback<int> ActiveIndexChanged, Orientation (Horizontal|Vertical), bool ManualActivation (activate on Enter/Space vs focus), RenderFragment? Tabs, RenderFragment? Panels.
  • Accessibility: role="tablist", tabs role="tab" with aria-selected, aria-controls, panels role="tabpanel" with aria-labelledby.
  • Keyboard: Arrow keys move focus, Home/End jump, Enter/Space activate when ManualActivation=true.
  • Tokens: active/hover/focus ring; density affects tab height/padding; high-contrast overrides.
  • RTL: reverse Left/Right semantics.
  • Gallery: variants (underline/contained), vertical tabs, manual vs automatic activation, many tabs with overflow.
Task COMP-LIB-T147 — Accordion (E2E)

Title: Implement token-driven Accordion with multi/single expansion and a11y

Description: Build Accordion with AccordionItem components supporting single or multiple open items, animated expand/collapse (respect reduced motion), and full ARIA semantics.

Implementation details:

  • Files: src/Components/Navigation/Accordion/*.razor.
  • Parameters: bool Multi, ISet<string> ExpandedKeys, EventCallback<ISet<string>> ExpandedKeysChanged, string Key on each item, bool Disabled.
  • Accessibility: header button controls region via aria-controls; region role="region" with aria-labelledby; aria-expanded on header.
  • Keyboard: Up/Down moves between headers, Home/End jump; Enter/Space toggle.
  • Motion: smooth height transition; disable on reduced motion.
  • Tokens: surface/elevation for header and region; focus ring on header; density-based paddings.
  • Gallery: demos for single vs multi, disabled items, long content, nested components (forms inside).
Task COMP-LIB-T148 — Breadcrumbs (E2E)

Title: Implement Breadcrumbs with truncation, overflow menu, and ARIA

Description: Provide Breadcrumbs with tokenized separators, optional overflow collapsing for long paths, and correct navigation/ARIA semantics.

Implementation details:

  • Files: src/Components/Navigation/Breadcrumbs/*.razor.
  • Parameters: IEnumerable<BreadcrumbItem> Items { Text, Href, Disabled }, int MaxItems (collapses middle into overflow), string Separator (icon or text).
  • Accessibility: nav with aria-label="Breadcrumb"; list ol/li; current page marked with aria-current="page".
  • Overflow: middle items tucked into a Menu (or simple Popover) with keyboard support.
  • Tokens: subtle separators, hover/focus styles; density adjusts spacing; RTL flips chevrons.
  • Gallery: short path, long path with overflow, RTL example, icon separators.
Task COMP-LIB-T149 — Keyboard Maps & Live A11y Hints (E2E)

Title: Add keyboard mapping overlays and live region hints in Gallery

Description: For Tabs and Accordion demos, display a small “Keyboard” panel listing supported keys and announce state changes (e.g., “Tab 3 selected”, “Section collapsed”) via LiveRegionService.

Implementation details:

  • Gallery utilities: KeyboardHelp.razor panel; A11yAnnouncer wrapper that calls AnnouncePolite(string) on selection/toggle.
  • Ensure no duplicate announcements; debounce where necessary.
Task COMP-LIB-T150 — Optional Adapter Bridges (E2E)

Title: Provide minimal bridges for adapters (Flowbite/DaisyUI)

Description: Map Tabs/Accordion/Breadcrumbs visuals to Flowbite/DaisyUI when those adapters are active (optional). Keep logic in core components, override only classes/markup shells.

Implementation details:

  • Strategy: conditional CSS class providers or partials that supply kit-specific classes.
  • Flowbite/DaisyUI: add small style maps and verify with Gallery adapter switch.
  • No hardcoded colors—use tokens; keep a11y roles identical.
Task COMP-LIB-T151 — Tests: Tabs/Accordion/Breadcrumbs (E2E)

Title: Unit + a11y tests for navigation components (keyboard/ARIA/RTL)

Description: Cover keyboard flows, ARIA linkage, controlled/uncontrolled state, and RTL behavior. Include snapshot tests for base markup.

Implementation details:

  • TabsTests: focus move with Arrows/Home/End; manual activation toggle; aria-controls/aria-labelledby relationships; RTL arrows flipped.
  • AccordionTests: aria-expanded toggling; region linkage; multi vs single expansion; reduced motion snapshot.
  • BreadcrumbsTests: aria-current on last item; overflow menu keyboard; RTL chevrons orientation.
  • Axe/pa11y scans for Gallery navigation pages.
Task COMP-LIB-T152 — Documentation & Snippets (E2E)

Title: Author docs for Tabs, Accordion, and Breadcrumbs with keyboard maps

Description: Write comprehensive docs with usage, parameters, accessibility/keyboard tables, theming/RTL notes, and copyable snippets linking back to Gallery.

Implementation details:

  • Docs: docs/components-tabs.md, docs/components-accordion.md, docs/components-breadcrumbs.md.
  • Include “Keyboard Reference” tables and adapter styling notes.
  • Troubleshooting: focus-management pitfalls, overflow handling, RTL arrow semantics.

Feature — COMP-LIB-F24 — Async & State Patterns

Goal: Provide consistent async/loading patterns: Spinner, Skeleton, ProgressBar, an AsyncButton pattern (OnClickAsync, busy/disabled), and a global IsBusy overlay surfaced via IUiKitAdapter. All visuals are token-driven, accessible, RTL-aware, and respect reduced motion. DoD: Components render with tokens only; a11y roles/attributes validated; adapters expose a global busy overlay; Gallery demos and copyable snippets provided; tests cover behaviors and a11y.

Task COMP-LIB-T153 — Loading Indicators: Spinner, Skeleton, ProgressBar (E2E)

Title: Implement token-driven Spinner, Skeleton, and ProgressBar components

Description: Add lightweight loading primitives with accessible semantics and reduced-motion support. Spinner and ProgressBar include determinate/indeterminate modes; Skeleton supports shapes and animated shimmer (disabled under reduced motion).

Implementation details:

  • Files: src/Components/Loaders/Spinner.razor, Skeleton.razor, ProgressBar.razor (+ scoped CSS).
  • Spinner: Size (xs|sm|md|lg), Label (visually hidden but SR-readable), determinate option with Value 0–100.
  • Skeleton: Variant (text|rect|circle), Width, Height, Lines, Animated=true|false.
  • ProgressBar: Value 0–100, Indeterminate, optional ShowLabel, Min/Max.
  • Accessibility:
    • Spinner/Skeleton: role="status", aria-live="polite", offscreen label.
    • ProgressBar: role="progressbar", aria-valuenow/min/max; when indeterminate, omit valuenow.
  • Tokens: foreground/background, focus ring (when focusable), density impacts sizes; reduced motion disables shimmer/spin transitions.
  • RTL: widths and inline progress remain logical (no visual dependence).
Task COMP-LIB-T154 — AsyncButton Pattern (E2E)

Title: Create AsyncButton with OnClickAsync, busy/disabled states, and cancellation

Description: Extend Button behavior to handle async operations safely: disable while running, show inline Spinner, handle exceptions, and support optional cancellation token with a cancel affordance.

Implementation details:

  • File: src/Components/Button/AsyncButton.razor.
  • Parameters: Func<CancellationToken, Task> OnClickAsync, bool ShowSpinner=true, bool AllowCancel=false, RenderFragment? BusyContent.
  • Behavior:
    • On click → set busy, disable interactions, render spinner or BusyContent.
    • If AllowCancel → show small cancel icon/button; signal CancellationTokenSource.
    • Re-enable on completion/failure; raise OnCompleted(Exception? ex) event/callback.
  • Accessibility: aria-busy="true" while running; tooltip/aria-label for Cancel control.
  • Tokens: re-use Button variants; spinner sized to button line-height.
  • Keyboard: Space/Enter triggers; cancel control focusable.
Task COMP-LIB-T155 — Global Busy Overlay via Adapter (E2E)

Title: Add IUiBusyAdapter and default Tokens implementation for global overlay

Description: Introduce a new optional adapter contract to show a full-page (or container) busy overlay with message and progress. Provide a tokens-based default and wire it into Gallery; allow kit adapters to replace it.

Implementation details:

  • Contract: IUiBusyAdapter with ShowAsync(BusyRequest), UpdateAsync(BusyUpdate), HideAsync().
  • Models: BusyRequest { string? Message; bool Indeterminate; int? Value; }, BusyUpdate { bool? Indeterminate; int? Value; string? Message; }.
  • Default: BusyTokensAdapter + BusyOverlayHost.razor (portal).
  • Behavior: body scroll lock, focus trap inside overlay if interactive; otherwise mark inert background (ARIA).
  • Accessibility: role="alertdialog" if interactive; otherwise role="status" with polite announcements; aria-busy on root container.
  • UiOptions: high-contrast styles; reduced motion = fade-only.
  • DI: extend AddUiKitAdapters() to register IUiBusyAdapter with tokens default; external kits can override.

Title: Add Async & Loading demos with copyable Razor snippets

Description: Create Gallery pages showing Spinner/Skeleton/ProgressBar, AsyncButton patterns (with cancel), and a Global Busy overlay with determinate/indeterminate examples.

Implementation details:

  • Pages: LoadingDemo.razor (all indicators), AsyncButtonDemo.razor, BusyOverlayDemo.razor.
  • Scenarios:
    • Spinner sizes; Skeleton list/cards; ProgressBar determinate vs indeterminate.
    • AsyncButton calling mocked async ops; error handling example; cancel-enabled.
    • Busy overlay while “loading data” with staged updates 0→100%.
  • Include “Copy snippet” buttons and adapter DI snippet for Busy overlay.
Task COMP-LIB-T157 — Tests & A11y (E2E)

Title: Add unit/a11y tests for loaders, AsyncButton, and Busy overlay

Description: Validate roles/ARIA, busy states, progress updates, cancellation, and reduced-motion behavior. Include snapshot tests for stable DOM structures.

Implementation details:

  • SpinnerTests: role/status, label announced, reduced-motion disables spin class.
  • SkeletonTests: animated vs static; correct shapes/sizes; reduced-motion off.
  • ProgressBarTests: role="progressbar", valuenow/min/max logic; indeterminate path.
  • AsyncButtonTests: disables on run; shows spinner/content; cancel triggers CTS; OnCompleted fired.
  • BusyOverlayTests: overlay shows/hides; traps focus when interactive; announces message; updates valuetext.
  • Add axe/pa11y checks for demo pages.
Task COMP-LIB-T158 — Documentation (E2E)

Title: Author async/state patterns docs with guidelines and pitfalls

Description: Document best practices for async operations in UI: when to use Spinner vs Skeleton vs ProgressBar, implementing AsyncButton, and invoking the Busy overlay via adapter.

Implementation details:

  • Docs: docs/patterns-async-and-state.md.
  • Sections: Choosing the right indicator, Accessibility (roles/ARIA), Reduced motion, RTL, Error handling, Cancellation patterns, Adapter integration.
  • Cross-link to Gallery demos and adapter guides.

Feature — COMP-LIB-F25 — Theming & Density Extensions

Goal: Enable advanced customization of themes and densities beyond the base tokens: introduce a custom theme overrides loader (tenant brand CSS injection), add per-component density overrides (beyond compact/cozy/comfortable), and validate runtime theme switching correctness and performance with automated tests. DoD: Apps can inject an additional theme CSS (scoped or global), components honor per-component density overrides, and runtime switching is validated by automated MutationObserver/e2e tests with no visual regressions or raw-color drift.

Task COMP-LIB-T159 — Custom Theme Overrides Loader (E2E)

Title: Implement loader to inject tenant brand CSS at startup or per-scope

Description: Provide a small service + Razor helper to load optional override CSS files (global or scoped) that extend token variables and utilities without breaking static web assets. Support multi-tenant scenarios and late-loaded brands.

Implementation details:

  • ThemeOverrideService with APIs:
    • LoadGlobalAsync(Uri cssUrl) (adds <link> to <head>)
    • LoadScopedAsync(ElementReference scope, string cssText) (injects <style> inside scope)
  • Razor helper <ThemeOverrides Link="..." Css="..." Scoped="true|false" />.
  • Ensure overrides only redefine CSS variables (e.g., --cs-*) and never introduce raw hex in component code.
  • Persist selected brand in localStorage; re-apply on reload.
  • Add safety: timeout + error logging if CSS fails to load.
Task COMP-LIB-T160 — Theme Registry & Precedence Rules (E2E)

Title: Add theme registry and deterministic cascade order

Description: Create a registry describing available themes (light/dark/brand) with explicit precedence so overrides always load after base tokens and before component-specific tweaks.

Implementation details:

  • ThemeRegistry model: { Id, DisplayName, CssHref?, IsDefault, IsHighContrast }.
  • Load order: Base Tokens → Selected Theme (light/dark) → High-Contrast (optional) → Brand Overrides.
  • Expose CurrentThemeId via UiContextService; raise change events to trigger reflow.
  • Validate _content/{PackageId}/... still resolves when packaged.
Task COMP-LIB-T161 — Per-Component Density Overrides (E2E)

Title: Support densities beyond compact/cozy/comfortable with local overrides

Description: Let consumers opt into component-level density (e.g., ultra-compact TextField, roomy Modal) without affecting global UiOptions. Provide consistent attribute/class contracts and token scaling.

Implementation details:

  • Add optional DensityOverride parameter to core components (Button, TextField, Modal, future controls): null|UltraCompact|Compact|Cozy|Comfortable|Spacious.
  • Map to attributes/classes like data-density="ultra-compact" on the component root; tokens compute paddings/line-heights accordingly.
  • Provide CSS utilities: .density-ultra-compact, .density-spacious backed by token scales.
  • Ensure overrides nest correctly with global density (component wins locally).
Task COMP-LIB-T162 — Runtime Theme Switching Validation (E2E)

Title: Add MutationObserver/e2e tests to validate live theme/density changes

Description: Implement automated tests that flip themes/density/HC/RTL at runtime and verify DOM/class/attribute transitions, contrast constraints, and absence of layout thrash.

Implementation details:

  • Playwright e2e: change theme via Gallery Settings; assert tokens applied (computed style checks on sample elements).
  • MutationObserver test helper: track attribute changes (data-theme, data-density, data-a11y) and measure repaint count (rough heuristic).
  • Axe/pa11y re-run after theme flip to catch contrast regressions.
  • CI gate: fail on missing attributes or contrast violations.

Title: Add “Brand & Density” lab with live override loader and per-component density toggles

Description: Create a dedicated Gallery page to load brand CSS overrides, switch themes, and toggle per-component density side-by-side to visualize impact.

Implementation details:

  • Page BrandAndDensityDemo.razor:
    • Upload or select brand CSS URL → calls ThemeOverrideService.LoadGlobalAsync.
    • Toggles: theme (light/dark), high-contrast, RTL, global density, and per-component density knobs.
    • Before/After panels rendering Button/TextField/Modal and key data components.
  • “Copy setup” snippet shows how to register the loader and apply overrides.
Task COMP-LIB-T164 — Docs: Theming & Density Extensions (E2E)

Title: Author documentation for overrides, registry, and per-component densities

Description: Provide a comprehensive guide on extending themes, adding brand CSS, using per-component density, and validating runtime switches.

Implementation details:

  • docs/theming-extensions.md:
    • Concepts: token layers, cascade order, registry.
    • How-to: load global/scoped overrides, author CSS that only modifies --cs-* vars.
    • Per-component density examples and recommended scales.
    • Testing: running e2e and MutationObserver checks.
    • Troubleshooting: specificity, z-index, cache busting.
Task COMP-LIB-T165 — Safeguards & Linting (E2E)

Title: Add lint rules and CI checks to prevent unsafe overrides

Description: Extend token-drift checker to scan override bundles in CI (optional mode) and warn when non-variable color literals are used or when unsupported CSS properties threaten accessibility.

Implementation details:

  • Extend token-drift-check to a “brand override” mode that warns (not fails) on raw colors but suggests mapping to variables.
  • Contrast probe on brand palettes vs content tokens; flag sub-AA pairs.
  • CI summary section: “Brand Overrides Health” with actionable hints.

Feature — COMP-LIB-F26 — RTL & Globalization Enhancements

Goal: Strengthen right-to-left (RTL) and globalization support across the library. Provide logical-direction styles (margin-inline, padding-inline), culture-aware date/number formatting helpers, and expand RESX coverage with a robust fallback strategy. Ensure components behave correctly under RTL and multiple cultures, including keyboard semantics and layout. DoD: Library renders correctly with dir="rtl"; helpers format dates/numbers per culture; expanded resources compiled (neutral + locales); Gallery exposes RTL/culture toggles; tests cover RTL layout, keyboard mirroring, and resource fallback.

Task COMP-LIB-T166 — RTL Logical Styles & Utilities (E2E)

Title: Add dir="rtl" aware utilities and replace left/right with logical start/end

Description: Introduce CSS utilities and component refactors that use logical properties (margin-inline, padding-inline, inset-inline, border-inline) and direction-aware icons/chevrons. Ensure keyboard semantics mirror in RTL (e.g., ArrowLeft/Right behaviors).

Implementation details:

  • Create rtl.css utilities: .ms-*/.me-* mapping to margin-inline-start/end, same for padding and borders.
  • Replace L/R classes in components with logical counterparts (Tabs, Breadcrumbs chevrons, Select popovers, Dialog close alignment).
  • Add small helper RtlDirectionService to query current dir and expose IsRtl for components that need conditional logic (e.g., arrow keys).
  • Update keyboard handlers to flip Left/Right where appropriate (Tabs, FocusZone horizontal).
  • Gallery: persistent RTL toggle in Settings; verify all showcased components.
Task COMP-LIB-T167 — Culture-Aware Formatting Helpers (E2E)

Title: Provide date/number formatting utilities with culture injection

Description: Ship simple, dependency-free helpers for culture-aware formatting of dates, times, and numbers to reduce duplication and ensure consistent output across components and samples.

Implementation details:

  • Globalization/Format.cs:
    • FormatDate(DateTime | DateOnly, CultureInfo? culture = null, string? format = null)
    • FormatNumber(decimal | double | int, CultureInfo? culture = null, string? format = null)
    • ParseDate(string, CultureInfo? culture) (best-effort; used in samples)
  • Inject culture via CultureInfo.CurrentCulture/UICulture (set from Gallery or app).
  • Integrate in: DatePicker (header month/year), Validation messages with numbers, demo content in Gallery.
  • Tests: culture matrix (en-US, ru-RU, he-IL) asserting separators, month names, week start.
Task COMP-LIB-T168 — Expanded RESX Coverage & Fallback Strategy (E2E)

Title: Add more sample locales and implement resilient resource fallback

Description: Extend resources beyond en/ru/he and document a robust fallback chain (e.g., fr-CA → fr → neutral). Add analyzer/CI checks for missing keys and ensure neutral strings remain complete.

Implementation details:

  • Add locales: fr, es, de (sample coverage for common keys).
  • Implement fallback: rely on .NET satellite assembly fallback; document the chain in docs/i18n.md.
  • CI: update missing-key checker to scan all locales; fail on missing neutral keys, warn on empty localized values.
  • Component pass: ensure all ARIA labels/tooltips/error strings use IStringLocalizer.
  • Gallery: culture selector includes new locales; validate layout/RTL unaffected.

Feature — COMP-LIB-F27 - Testing Extensions

Goal: Strengthen test confidence with visual regression (Playwright screenshots), broader bUnit coverage for new form/async components, and automated axe accessibility scans over advanced demos. Reduce flakiness with deterministic fixtures, snapshot normalization, and CI gating. DoD: Playwright captures stable screenshots and diffs in CI; bUnit covers Select/Choice/DatePicker/TextArea/Async flows; axe scans run on Gallery advanced pages; artifacts published with readable failure diffs.

Task COMP-LIB-T169 — Visual Regression via Playwright (E2E)

Title: Add Playwright screenshot tests for Gallery critical states

Description: Configure Playwright to render key Gallery pages and capture baseline screenshots under deterministic settings (fixed viewport, fonts, theme/density). Produce diffs on regressions and publish artifacts.

Implementation details:

  • Add tests/e2e/playwright.config.ts with: fixed timezone/locale, viewport (1280×900), prefers-reduced-motion: reduce, web-safe font fallback.
  • Scenarios: Button/TextField/Modal matrices; Adapters (Tokens/Flowbite/DaisyUI); Select (open list), DatePicker (open month grid), Table/Grid (paged), Tabs/Accordion states.
  • Use toHaveScreenshot({ maxDiffPixelRatio: 0.003 }); store baselines under tests/e2e/__screenshots__.
  • CI: upload diffs and current shots as artifacts; fail on diff > threshold; allow per-test --update-snapshots only on approved branches.
Task COMP-LIB-T170 — bUnit Coverage: Forms & Async (E2E)

Title: Expand unit tests for Select/Checkbox/Radio/DatePicker/TextArea and AsyncButton

Description: Add granular bUnit tests that validate rendering, binding, events, ARIA, keyboard flows, and RTL for advanced form controls and async scenarios.

Implementation details:

  • Files:

  • tests/SelectTests.cs, ChoiceGroupTests.cs, DatePickerTests.cs, TextAreaTests.cs, AsyncButtonTests.cs.

  • Coverage: controlled/uncontrolled value changes; validation with EditForm; keyboard maps (arrows/Home/End/Esc/typeahead); RTL arrow mirroring; AsyncButton busy/cancel/exception paths.
  • Snapshot only stable structures; reuse normalization helper; assert no raw hex via token drift guard.
Task COMP-LIB-T171 — Axe Scans for Advanced Components (E2E)

Title: Run axe on advanced Gallery routes and fail on critical issues

Description: Add an axe pass targeting advanced pages (Select, DatePicker, Table/Grid, Tabs/Accordion, Adapters). Store JSON/HTML reports and make critical/serious violations fail CI.

Implementation details:

  • Use @axe-core/playwright in e2e or pa11y CLI against prerendered routes.
  • Routes: /select, /choice-group, /datepicker, /table-grid, /tabs, /accordion, /adapters.
  • Artifact path: artifacts/a11y/*; CI summary links to each report.
Task COMP-LIB-T172 — Flake Reduction & Determinism (E2E)

Title: Stabilize tests with deterministic environment and network isolation

Description: Ensure repeatable runs by fixing random seeds, disabling animations, mocking timers/network, and waiting for idle UI before snapshots.

Implementation details:

  • Playwright: page.route('**/*', route => route.fulfill({ body: '' })) for externals not required; page.waitForLoadState('networkidle') before shots.
  • Force CSS animation-duration: 0ms for tests; set reduced-motion in config.
  • Freeze date/time via page.addInitScript to a fixed ISO date; use seeded data for tables.
  • Retries: enable 1 retry on CI only; tag known-slow tests and parallelize the rest.
Task COMP-LIB-T173 — Reporting & Developer Docs (E2E)

Title: Publish rich test artifacts and author “Testing Extensions” guide

Description: Enhance CI summaries with screenshot diffs, a11y links, and coverage deltas; document how to write/approve visual tests, add axe routes, and expand bUnit coverage.

Implementation details:

  • CI summary: markdown table of e2e suites with pass/fail, links to diffs/reports; coverage delta vs previous commit.
  • Docs: docs/testing-extensions.md → Playwright setup, when to update baselines, axe routing tips, bUnit patterns for async/RTL, flakiness checklist.
  • Add npm scripts: test:vr, test:vr:update, test:a11y.

Feature — COMP-LIB-F28 - Performance & Bundling

Goal: Keep the library lean and fast. Add a bundle analyzer step to detect CSS/JS size regressions, implement lazy loading for heavy components (DataGrid, DatePicker), and ensure adapters are tree-shaken when unused. Provide CI gates, Gallery perf dashboards, and guidance for consumers. DoD: CI produces size reports and fails on configured thresholds; DataGrid/DatePicker load lazily without breaking a11y; unused adapter code isn’t emitted; docs include optimization guidance.

Task COMP-LIB-T174 — Bundle Analyzer & Size Budgets (E2E)

Title: Add CSS/JS bundle analyzer and per-artifact size budgets

Description: Integrate a bundle analyzer for Gallery and sample consumer builds to measure JS, CSS (token + Tailwind), and static assets. Establish budgets and fail CI on regressions.

Implementation details:

  • Add build step to emit size manifest (e.g., via rollup-plugin-visualizer/webpack-bundle-analyzer for any JS, and a CSS-size reporter).
  • Track: total CSS, token CSS, component CSS, JS interop (if any).
  • Create artifacts/size/manifest.json with per-file bytes + gzip/brotli.
  • CI compares against last successful build; thresholds: e.g., +20KB total CSS or +5KB per component = fail.
  • PR summary posts a delta table; store HTML treemap as artifact.
Task COMP-LIB-T175 — Lazy Loading Infrastructure (E2E)

Title: Introduce lazy component loader with a11y-safe placeholders

Description: Create a small utility to defer heavy component trees until visible/needed, with tokenized Skeleton/Spinner placeholders and preserved ARIA semantics.

Implementation details:

  • LazyRender.razor: props Func<Task<RenderFragment>> Load, RenderFragment? Placeholder, IntersectionObserver fallback to manual trigger, timeout/cancel support.
  • Ensure placeholder carries appropriate roles (e.g., status) and size.
  • Provide helper to preload in idle time.
  • Works in Blazor Server and WASM; disable animations when reduced motion.
  • Gallery: “Lazy Rendering” demo comparing first contentful render.
Task COMP-LIB-T176 — Component Lazy Loading: DataGrid & DatePicker (E2E)

Title: Apply lazy loading to DataGrid and DatePicker with seamless UX

Description: Split heavy logic/markup of Table/Grid and DatePicker behind LazyRender. Keep keyboard/a11y intact and avoid layout shift via Skeletons.

Implementation details:

  • DataGrid: delay advanced subfeatures (virtualization prep, adapters) until the table becomes visible or user interacts.
  • DatePicker: load calendar grid on first open; cache thereafter.
  • Maintain focus order: auto-focus first interactive child after load; announce with LiveRegion (“Loaded”).
  • Add perf counters (ms to first interaction) to Gallery perf panel.
Task COMP-LIB-T177 — Adapter Tree-Shaking (E2E)

Title: Ensure unused adapters are not included in consumer builds

Description: Restructure adapters so only the registered adapter ships. Separate packages already help; add conditional DI and linker-friendly patterns to strip unused code.

Implementation details:

  • Keep adapters in separate assemblies (Tokens/Flowbite/DaisyUI).
  • Use TryAdd + Replace with no reflection-based discovery; avoid static cross-refs.
  • Mark internal helpers with DynamicDependency only where necessary to keep linker accurate.
  • Add a linker test: minimal consumer app references library but not adapters → check output size and absence of adapter types.
  • Doc a “Minimal footprint” recipe (Tokens-only vs external kits).
Task COMP-LIB-T178 — CI Perf Gate & Docs (E2E)

Title: Add performance gate in CI and author optimization guide

Description: Fail builds on size regressions and publish a Performance section in docs that explains lazy loading hooks, skeletons, and adapter tree-shaking.

Implementation details:

  • CI job “perf-check”: compare size manifest to baseline; fail on budget breach.
  • Publish treemap + per-bundle deltas in PR comment.
  • Docs docs/performance-and-bundling.md:
    • Using LazyRender and placeholders
    • Deferring DatePicker/DataGrid
    • Keeping adapters out of the bundle
    • Troubleshooting (why size grew, how to bisect)

Feature — COMP-LIB-F29 - Design System Sync

Goal: Keep the component library’s tokens in lockstep with the Factory design tokens source of truth. Add a CI step that validates token names/types/paths against the reference repo, fails on drift (removed/renamed/changed type), and generates a human-friendly tokens-map.md diff on releases. DoD: CI validation runs on every PR; build fails on breaking drift; non-breaking additions surface as warnings; release artifacts include tokens-map.md with change summary and impacted components.

Task COMP-LIB-T179 — Validate Tokens Against Factory Repo (E2E)

Title: Implement token validator that compares local tokens to Factory design tokens

Description: Build a deterministic validator that fetches/parses the Factory tokens (via git submodule, package, or read-only HTTP export) and compares them to the library’s emitted CSS variables/JSON.

Implementation details:

  • Acquisition:
    • Preferred: add git submodule factory-design-tokens at a pinned ref; fallback: npm/pkg feed or ZIP URL with checksum.
  • Inputs:
    • Reference: factory-design-tokens/**/*.json (or W3C Design Tokens format)
    • Local: generated JSON snapshot of our tokens (export step from the RCL build, e.g., artifacts/tokens/local.json)
  • Validation rules:
    • Name parity: each reference token must exist locally with identical canonical path (e.g., color.action.bg).
    • Type parity: color/number/typography/spacing matches.
    • Value parity (optional): skew allowed if we intentionally override; gate only when flagged locked=true.
  • Output: machine-readable tokens-validate.json + console summary (added/removed/renamed/changed-type).
Task COMP-LIB-T180 — Drift Detection & Build Gate (E2E)

Title: Fail build on token drift; warn on safe additions; post PR summary

Description: Wire the validator into CI with severity levels. Breaking drifts fail the build (removed, renamed, type-changed). Additions default to warn unless the policy requires explicit acceptance.

Implementation details:

  • Severity mapping:
    • removed|renamed|typeChanged → error (fail)
    • added → warning (non-blocking)
    • valueChanged → info unless locked=true then error
  • CI integration: run after restore/build, before tests; publish artifacts/tokens/tokens-validate.json.
  • PR UX: post a markdown table with deltas (emoji-coded) and remediation tips (rename map, deprecation shim).
  • Allowlist: build/tools/tokens-allow.json with expiry (date + PR link) to temporarily unblock urgent merges.
Task COMP-LIB-T181 — Generate tokens-map.md Diff for Releases (E2E)

Title: Produce human-friendly tokens map + diff and attach to releases

Description: On tagged releases, emit tokens-map.md showing token → CSS variable mapping, status (added/removed/renamed), last changed commit, and impacted components discovered via grep. Publish as artifact and include in release notes.

Implementation details:

  • Generation:
    • Build a Markdown with sections: Overview, Changes since last tag, Full map (alphabetical), Impact report (components & CSS files).
    • Link each token to its reference path in the Factory repo (permalink to commit).
  • Automation:
    • Release pipeline step runs after packaging; uploads tokens-map.md and a CSV/JSON variant.
    • Docs site: copy tokens-map.md into docs/ under a versioned folder (docs/tokens/{version}/tokens-map.md).
  • Quality:
    • Ensure line-stable output (sorting) for clean diffs between releases.
    • If drift errors exist, block release and include the validator summary in job logs.

Feature — COMP-LIB-F30 - Storybook/Docs Portal

Goal: Provide an optional Storybook-like experience (side-by-side with MkDocs) for interactive component exploration. Include live knobs/controls for props (density, theme, locale, RTL, motion) and inline ADR references so engineers see design decisions next to examples. Keep it optional (not required by consumers) and fully token-driven. DoD: Portal runs locally and in CI preview; stories show interactive controls; knobs sync with UiOptions/i18n; ADR links render beside stories; docs cross-link to Gallery and MkDocs; tests verify key stories render and controls work.

Task COMP-LIB-T182 — Storybook Portal Scaffold (E2E)

Title: Create optional Storybook-like portal alongside MkDocs

Description: Add a lightweight stories host (e.g., samples/ComponentLibrary.Stories) that discovers .stories.razor files and renders them with a left nav + preview pane. Keep it independent of consumer apps and wired to tokens/Tailwind.

Implementation details:

  • Project: samples/ConnectSoft.Blazor.ComponentLibrary.Stories/
  • Navigation: auto-generate tree from folder structure (Components/Button/Button.stories.razor, etc.)
  • Shared layout with header links to MkDocs + Gallery
  • Build scripts: dotnet run local; optional static export for CI preview
Task COMP-LIB-T183 — Interactive Controls/Knobs (E2E)

Title: Implement live knobs for theme/density/locale/RTL/motion + component props

Description: Add a Controls panel that binds to UiOptions and common component props. Controls update the preview in real time and persist to localStorage.

Implementation details:

  • Global controls: Theme (light/dark), Density, High-Contrast, RTL, Motion (reduced)
  • Per-story controls: simple auto-generated inputs for booleans/enums/numbers/strings (e.g., Button Variant, Size, Disabled)
  • Two-way sync: controls ⇄ story parameters; reset-to-defaults button
  • Persist last used settings across sessions
Task COMP-LIB-T184 — Story Files for Baseline & Advanced Components (E2E)

Title: Author .stories.razor for Button, TextField, Modal, Select, DatePicker, Tabs, Table/Grid

Description: Provide focused stories (one scenario per file) with minimal scaffolding. Each story includes a description, usage snippet, and links to docs + ADRs.

Implementation details:

  • Structure: Stories/Components/{Button|TextField|Modal|...}/*.stories.razor
  • Include sample args/controls metadata so the portal can render knobs
  • Show localized labels via IStringLocalizer (EN/RU/HE) and RTL toggle

Title: Render ADR links/abstracts near relevant stories

Description: Pull ADR metadata (title, decision, status, link) and surface it in a right-side panel for stories that relate to tokens, adapters, options, etc.

Implementation details:

  • Simple parser for docs/adr/*.md front-matter (id/title/status) + first paragraph
  • “Related ADRs” panel with links: e.g., Tokens, Adapters, UiOptions
  • Fallback when ADRs not found; ensure links open MkDocs page
Task COMP-LIB-T186 — CI Preview & Linting (E2E)

Title: Build and publish portal preview; lint stories for accessibility

Description: Add CI job to build the portal, publish as an artifact (or temporary static site), and run axe checks on selected stories.

Implementation details:

  • CI: build → stories:build → stories:a11y
  • Axe routes: Button, Modal, Select, DatePicker, Tabs, Table/Grid (critical flows)
  • Publish artifacts: static bundle + a11y reports; PR comment with preview link (if infra allows)
Task COMP-LIB-T187 — Tests & Docs (E2E)

Title: Add smoke tests for stories and write “Stories Portal” guide

Description: Ensure key stories render with default controls and respond to knob changes. Document how to add new stories, define controls, and link ADRs.

Implementation details:

  • bUnit/Playwright: open a few stories, toggle controls (theme/density/props), assert changes in preview
  • Docs: docs/stories-portal.md with folder conventions, control metadata schema, ADR linking how-to, and CI preview notes

Feature — COMP-LIB-F31 - Enterprise-Grade Security

Goal: Raise the bar on security for the component library and gallery. Add a Content Security Policy (CSP) test harness that proves we don’t require unsafe-inline, generate an SBOM for all shipped NuGet packages, and enforce a static analysis pass that flags unsafe HTML/MarkupString usage and risky render patterns. DoD: Gallery and samples run under strict CSP (no unsafe-inline, no unsafe-eval) without violations; SBOM artifacts (SPDX/CycloneDX) are produced and attached to releases; analyzer blocks unsafe markup patterns in PRs with actionable guidance.

Task COMP-LIB-T188 — CSP Test Harness (E2E)

Title: Enforce strict CSP (no unsafe-inline) with automated validation

Description: Add a reusable CSP configuration and validation suite for Gallery and sample apps. Run with Content-Security-Policy-Report-Only first, then enforce. Remove any inline scripts/styles; ensure tokens/Tailwind and adapters work with nonces or externalized assets.

Implementation details:

  • Headers: set default-src 'self'; script-src 'self' 'nonce-{generated}'; style-src 'self'; img-src 'self' data:; font-src 'self'; connect-src 'self'; frame-ancestors 'none'.
  • Blazor specifics: move bootstrap scripts to external files; attach a per-request nonce to framework tags if required; no inline <style> or style= in samples.
  • Gallery: add a CSP report endpoint (log-only) to capture violations; convert to enforcing after green runs.
  • Playwright: navigate critical routes (components, adapters) and assert zero CSP violations in console/network.
  • Docs: checklist for consumers (how to adopt the same CSP).
Task COMP-LIB-T189 — SBOM Generation for NuGet (E2E)

Title: Produce SPDX/CycloneDX SBOMs during packaging and publish with releases

Description: Generate SBOMs for the library and adapter packages at pack time, including transitive dependencies, hashes, and license metadata. Attach to release artifacts and store under artifacts/sbom/.

Implementation details:

  • Tooling: use dotnet sbom or CycloneDX for .NET; output CycloneDX JSON + SPDX tag-value.
  • Include package IDs/versions, integrity hashes, and license info; sign if required.
  • CI: run on pack stage; upload to artifacts; link from release notes and docs.
  • Add SECURITY.md/SUPPORT.md pointers for vulnerability reporting.
Task COMP-LIB-T190 — Static Analyzer for Unsafe Markup (E2E)

Title: Add analyzer rules to block unsafe HTML/MarkupString and raw markup insertion

Description: Introduce Roslyn/Razor analyzers (or custom rules) that flag dangerous patterns: MarkupString without sanitization, RenderTreeBuilder.AddMarkupContent, unescaped @((MarkupString)...), and risky JS interop that injects HTML. Provide code fixes and safe alternatives.

Implementation details:

  • Rules:
    • SEC001: MarkupString usage requires explicit justification attribute/comment and approved sanitizer.
    • SEC002: AddMarkupContent banned in components (use encoded AddContent/safe render fragments).
    • SEC003: Razor @Html.Raw-like patterns (if any) prohibited.
    • SEC004: JS interop that sets innerHTML flagged unless sanitizer wrapper used.
  • Add sample sanitizer abstraction (no heavy deps) for docs/tests.
  • CI: treat security rules as errors; provide suppression template with expiry + reason.
  • Docs: “Secure Markup” guide with before/after snippets and analyzer IDs.