Accretion UI Mitosis Accordion Library

Quick Links

• React Chromatic Storybook: https://69ae3d6f019c2b8f497fdd28-zwrtooohxn.chromatic.com/
• Angular Chromatic Storybook: https://69ae3de6fef62640081354ec-fbslbprsoe.chromatic.com/
• React package on npm: https://www.npmjs.com/package/@accretion-ui/react
• Angular package on npm: https://www.npmjs.com/package/@accretion-ui/angular

What this library is

This repository is a production-oriented starting point for a shared component library that is authored once and shipped as native packages for React and Angular. It currently ships one component, Accordion, because the goal is to validate the architecture, accessibility quality, SSR behavior, testing workflow, and documentation standard before scaling the library wider.

Why it matters

This setup reduces the usual tradeoff between consistency and framework fit. Design decisions, semantic tokens, accessibility expectations, and base interaction rules live in one shared source layer, while React and Angular consumers still receive framework-native packages instead of web component wrappers. That makes evaluation faster for both product and design stakeholders and keeps adoption simpler for application teams.

What can be validated quickly

Within a single session you can validate:

• the visual and interaction quality of the Accordion in both frameworks
• server-rendered markup and clean hydration in real SSR apps
• Storybook documentation quality for both targets
• Chromatic publishing for both Storybooks
• automated behavior coverage across unit, browser, and smoke checks

What Accordion enables

Accordion gives teams a structured way to reveal supporting detail without fragmenting a page. It works well for FAQs, rollout plans, pricing clarifications, policies, onboarding flows, and implementation handoff content where people need progressive disclosure without losing context.

How to evaluate quality quickly

Use these checks first:

1. Run both Storybooks and confirm the docs pages explain purpose, API, accessibility, and common usage patterns.
2. Run both SSR smoke apps and confirm the Accordion renders before hydration, then remains interactive after hydration.
3. Run the test and smoke commands to confirm keyboard support, controlled behavior, disabled handling, and Storybook page availability.

Published Storybooks:

• React Chromatic Storybook: https://69ae3d6f019c2b8f497fdd28-zwrtooohxn.chromatic.com/
• Angular Chromatic Storybook: https://69ae3de6fef62640081354ec-fbslbprsoe.chromatic.com/

Architecture Overview

The repo uses a layered approach:

• packages/core contains shared Accordion logic, types, token-driven CSS generation, and the Mitosis-authored low-level view parts.
• packages/react publishes the React package. It uses generated React view parts from Mitosis plus a thin React-native compound API for state, context, ids, and keyboard behavior.
• packages/angular publishes the Angular package. It uses native standalone host-bound primitives attached directly to real DOM elements so Angular consumers keep a one-element-per-part API without wrapper nodes.
• chromatic/react and chromatic/angular hold the Storybook surfaces used locally and in Chromatic.
• smoke-apps/react-next and smoke-apps/angular-ssr validate SSR and hydration in real framework runtimes.
• testing contains Vitest and Playwright coverage across logic, React behavior, SSR smoke apps, and Storybook availability.

Package Structure

packages/
  core/
  react/
  angular/
chromatic/
  react/
  angular/
smoke-apps/
  react-next/
  angular-ssr/
testing/
scripts/
tokens/

Local Development Setup

Requirements:

• Node.js 20.19+ is recommended
• npm 11+

Install dependencies:

npm install

Generate token-driven styles and Mitosis outputs:

npm run generate

How Mitosis Is Used

Mitosis is the shared authoring layer for the low-level Accordion view parts in packages/core/src/components/accordion. Those files generate native React and Angular view output through scripts/generate-mitosis.mjs.

The public package layers are intentionally thinner than a full wrapper library:

• React uses the generated Mitosis view parts directly and adds framework-native state/context handling.
• Angular keeps the generated view output in-repo for reference, but ships native standalone directives as the public API. This is an intentional tradeoff because the current Mitosis Angular target is not a reliable fit for compound, context-driven primitives that must preserve one host element per part.

How Code Generation Works

Token-derived styling is generated by:

npm run generate:styles

Mitosis output generation runs:

npm run generate:components

The style generator reads:

• tokens/primitives.json
• tokens/semantic/accordion.json

Build Packages

Build both publishable packages:

npm run build

Build React only:

npm run build:react

Build Angular only:

npm run build:angular

Build output locations:

• React package artifacts: packages/react/dist
• Angular package artifacts: dist/packages/angular

Run Storybook For React

npm run storybook:react

Default URL: http://127.0.0.1:6006 Published Chromatic URL: https://69ae3d6f019c2b8f497fdd28-zwrtooohxn.chromatic.com/

Run Storybook For Angular

npm run storybook:angular

Default URL: http://127.0.0.1:6007 Published Chromatic URL: https://69ae3de6fef62640081354ec-fbslbprsoe.chromatic.com/

Run Chromatic For React

The script reads CHROMATIC_PROJECT_TOKEN_REACT_MITOSIS from the environment.

npm run chromatic:react

After publishing, update the React Storybook links in:

• README.md
• packages/react/README.md

Run Chromatic For Angular

The script reads CHROMATIC_PROJECT_TOKEN_ANGULAR_MITOSIS from the environment.

npm run chromatic:angular

After publishing, update the Angular Storybook links in:

• README.md
• packages/angular/README.md

Run Tests

Run unit and integration coverage:

npm run test:unit

Run the Playwright suite:

npm run test:playwright

Run everything:

npm test

Run Smoke Tests

Run framework-specific browser smoke checks against production-style builds:

npm run smoke:react
npm run smoke:angular

Run both:

npm run smoke

Run SSR Validation Locally

SSR validation fetches the rendered HTML from the built smoke apps and confirms the Accordion markup, ids, and stylesheet references are present before browser hydration.

npm run validate:ssr:react
npm run validate:ssr:angular

Run both:

npm run validate:ssr

For local interactive SSR development:

npm run dev:react-ssr
npm run dev:angular-ssr

Release And Publish Workflow

This repo is set up as a publishable monorepo, but publishing is intentionally explicit.

1. Update package versions in packages/react/package.json and packages/angular/package.json.
2. Run npm run build.
3. Run npm test, npm run smoke, and npm run validate:ssr.
4. Run npm run chromatic:react and npm run chromatic:angular.
5. Update Storybook links in README.md, packages/react/README.md, and packages/angular/README.md to match the newest Chromatic builds.
6. Dry-run the publish artifacts with npm pack --dry-run in packages/react and dist/packages/angular.
7. Publish packages/react as @accretion-ui/react.
8. Publish dist/packages/angular as @accretion-ui/angular.

React is publishable directly from its package folder because the build writes into packages/react/dist. Angular is published from dist/packages/angular because the package is assembled after Angular compilation.

Known Limitations And Tradeoffs

• The Angular public package uses native directives instead of directly shipping the generated Mitosis Angular output. This keeps the compound API and one-element-per-part contract stable.
• Closed panel containers stay mounted in both targets so aria-controls targets remain stable, but panel content is unmounted by default unless keepMounted or hiddenUntilFound is enabled.
• React exposes hiddenUntilFound, but React DOM normalizes hidden values during SSR. The package corrects the attribute after hydration so browser find-in-page can still work, but the initial HTML is still serialized as standard hidden.
• The current repo is intentionally scoped to Accordion only. The structure is designed for expansion, but no placeholder components were added.