@seeqdev/qomponents 0.0.247-beta.1ab24b167f.20261008 → 0.0.247-beta.3f92cc4ece.20261020

package/README-internal.md

@@ -0,0 +1,278 @@
+# Qomponents
+
+WARNING: Any change to files under `src/` will be published publicly to the
+`@seeqdev/qomponents` package on npm. Review changes carefully and follow the
+release process.
+
+Qomponents is the UI component library used at Seeq. It's built with React, StyleX, and headless UI component
+libraries to codify the design standards of Seeq's web assets.
+
+## StyleX styling and themes
+
+The migration keeps qomponents a conventional StyleX library: named token exports in `.stylex.ts` modules,
+`createTheme` overrides, and component styles composed with `stylex.props`. Legacy CSS names, Tailwind mappings,
+and old theme selectors belong in a webserver compatibility adapter, not the permanent token API.
+
+### Shared control styles
+
+`TextField`, `TextArea`, `Select`, and `Checkbox` compose the shared border, hover/focus, invalid, and disabled
+styles in `src/styles/controls.ts`. Fixed border widths, radii, dimensions, and typography use `defineConsts`, so
+compiled CSS contains literal values. Components retain their own layout and native behavior. Checkbox and radio
+borders now use the same neutral/hover/disabled color contract as the other controls.
+
+### StyleX token modules
+
+- `src/theme/colors.stylex.ts` defines one color contract for the UI, including neutral colors and product accents.
+  Add future semantic color roles to this contract rather than introducing independently applied sub-themes.
+- `src/theme/controls.stylex.ts` contains fixed control dimensions and typography as compile-time constants.
+  Monorepo consumers can import them from the source-only `@seeqdev/qomponents/stylex` subpath.
+  This subpath is not published; external consumers use the compiled components and exported `themes`.
+- `src/theme/palette.stylex.ts` shares literal product accent values with the temporary webserver adapter.
+- `src/theme/themes.ts` exports `themes[product][mode]`, a complete theme for each product and light/dark mode.
+  Apply one theme with `stylex.props` at each boundary, including portal roots. Nested themes reset the whole
+  color contract; adding colors does not add more theme classes to the boundary.
+
+These modules use ordinary StyleX-generated variable names. Import definitions directly from their `.stylex`
+module; do not add a legacy-name token API or hardcode generated identifiers. Webserver's temporary
+[`legacyTheme.utilities.ts`](../webserver/app/src/styles/legacyTheme.utilities.ts) applies a complete product/mode
+theme alongside its existing `color_*`, `tw-dark`, and `light` classes. Its main switcher, standalone page roots,
+and local home screen dark boundaries use the adapter. Standalone page updates remove stale theme classes while
+preserving unrelated body classes. Portals mounted under `body` inherit the global theme; components that portal out
+of a local boundary must explicitly carry that boundary's theme during their migration.
+
+The adapter preserves legacy palette variables; it does not globally remap broad tokens such as disabled-gray,
+whose meanings differ across existing controls. Add role-specific Tailwind aliases only with the consumers that
+need them. Delete the class adapter once webserver's legacy theme selectors have no consumers.
+
+Components use these tokens and shared state styles. Colors use `defineVars` for theme switching; fixed
+dimensions and typography use `defineConsts` so generated CSS contains readable literal values. `themes` is exported from the
+public component barrel and compiled into the published package. Definitions for authoring new StyleX styles still
+come directly from the workspace `.stylex` modules.
+
+TextField keeps its current dimensions, font sizes, joined edges, placeholder colors, native disabled/read-only
+behavior, and number-input handling. Light fields inherit their containing surface; dark fields use the dark control
+surface. `fieldBackground` defaults to CSS `initial`, and `firstThatWorks` supplies the `inherit` fallback. Webserver's
+adapter overrides this token to white in light mode, preserving its legacy forms reset without coupling the library
+to that reset.
+
+`showError` also sets `aria-invalid` on the input. Consumer validation tests should assert invalid state
+(`toBeInvalid()`) rather than styling classes. When testing
+whether an error is surfaced before validation (for example, during loading), check `aria-invalid` directly:
+`toBeInvalid()` also checks native constraints such as `required`.
+
+Use `xstyle` for StyleX overrides; it is composed after the field's built-in styles. `extraClassNames` remains available
+for layout utilities, test hooks, and legacy CSS. Class-string order does not determine precedence. During migration,
+webserver declares its layer order before importing Tailwind: `theme, base, components, stylex, utilities`.
+This temporary host-side bridge preserves existing utility overrides while keeping resets below component styles.
+It does not change the library's generated CSS or StyleX composition API. Remove the bridge after webserver's
+utility overrides are migrated; new StyleX overrides should use `xstyle`.
+The existing `inputWidth` and `inputHeight` props remain explicit dimension overrides and preserve dynamic `xstyle`
+custom properties.
+
+For nested elements, use the component’s explicit StyleX slots instead of descendant selectors. For example,
+`Button.iconXstyle` styles its icon and composes after the icon’s built-in styles; the component’s root `xstyle`
+does not target its children.
+
+```tsx
+import * as stylex from '@stylexjs/stylex';
+import { TextField, themes } from '@seeqdev/qomponents';
+
+<div {...stylex.props(themes.analysis.dark)}>
+  <TextField placeholder="Name" />
+</div>;
+```
+
+Selecting these compiled themes requires only the StyleX runtime, not a compiler. Import the published `styles.css`
+as usual. Authoring new styles with `stylex.create` still requires a StyleX compiler.
+
+The shared `src/styles/controls.ts` definitions compose as base, invalid (when applicable), then disabled.
+Invalid and disabled styles replace every hover/focus/active border override as well as the default border.
+Components retain their own layout, shape, native disabled/read-only behavior, and focus accessibility treatment.
+TextField, TextArea, Select, and Checkbox share these definitions.
+
+Qomponents' source test projects compile StyleX locally. Browser tests use runtime injection because Vitest disables
+Vite HMR, which the compiler uses to refresh extracted development CSS. The published-package smoke test checks
+extracted default styles and an exported theme. Other
+workspace packages' Vitest pipelines are unchanged; webserver's Jest adapter now compiles StyleX before SWC.
+
+### Verification and legacy compatibility
+
+The component migration is complete. Qomponents' source, stories, Ladle, tests, published bundle, and example no
+longer need Tailwind. `src/styles.css` retains ordinary base typography, icon-font assets, and legacy font-icon
+support; `src/styles.build.css` adds the StyleX extraction marker for published builds and source previews.
+PostCSS remains a build-only dependency to resolve ordinary CSS imports before extraction; it generates no utilities.
+
+Webserver still uses Tailwind. Its temporary `app/src/styles/qomponentsLegacyTheme.css` owns the legacy CSS
+variables and utility aliases that previously came from qomponents. The existing `legacyTheme.utilities.ts`
+continues to apply StyleX themes alongside legacy selectors. Remove those adapters when their webserver consumers
+are migrated, not when publishing qomponents.
+
+Run the component/browser tests, type checks, lint, and `pnpm test:build`. The latter consumes the actual
+`dist/index.esm.js` and `dist/styles.css` in Chromium without a StyleX or Tailwind compiler. Check Ladle as well:
+a successful source transform cannot prove extracted CSS is delivered to its preview. Migration commits include
+webserver consumer-test updates; assertions should describe invalid, selected, or variant state rather than utility
+classes or StyleX hashes.
+
+## Local Development
+
+Note: ensure your local machine has updated dependencies first by running
+`gradlew :client:packages-qomponents:npmInstall`.
+
+Ladle is a component playground web application that takes our components' stories and lets you interact with them
+in a web browser. To start the Ladle server, run: `pnpm dev`.
+
+The shared Ladle Vite config preserves StyleX token imports through React's SWC transform so CSS extraction can
+load their definitions. Qomponents uses the `@stylex` marker in `src/styles.build.css` to deliver extracted CSS through
+Vite's normal CSS pipeline. Its shared Ladle and Vitest configs set `tailwind: false`. The standalone StyleX CSS
+endpoint is incompatible with Ladle's Koa middleware server.
+
+- Add or update components under `src/`.
+- Export public components and types from `src/index.ts`.
+- Components and stories use StyleX; themeable colors belong in the shared color contract.
+- Verify changes in both light and dark mode and across themes when applicable.
+
+### Ladle providers
+
+Other packages can import `QomponentsLadleProvider` from `@seeqdev/qomponents/ladle` into their `.ladle/components.tsx` to allow Qomponents to work properly.
+
+```tsx
+import { QomponentsLadleProvider } from '@seeqdev/qomponents/ladle';
+
+export const Provider = ({ children }) => <QomponentsLadleProvider>{children}</QomponentsLadleProvider>;
+```
+
+If your package also needs Ladle i18n integration, wrap `QomponentsLadleProvider` with `LadleProvider`:
+
+```tsx
+import { LadleProvider, createLadleI18n } from '@seeqdev/tools/ladle';
+import { QomponentsLadleProvider } from '@seeqdev/qomponents/ladle';
+
+export const Provider = ({ children }) => (
+  <LadleProvider i18n={myI18nInstance}>
+    <QomponentsLadleProvider>{children}</QomponentsLadleProvider>
+  </LadleProvider>
+);
+```
+
+## Typecheck
+
+To run `tsgo` on Qomponents, use: `gradlew :client:packages-qomponents:tsc`.
+
+## Format
+
+Format code with: `gradlew :client:packages-qomponents:pnpmLint`
+
+## Testing
+
+Vitest is split into projects:
+
+- `unit`: `src/**/*.unit.test.{ts,tsx}` (node fastest)
+- `component`: `src/**/*.test.{ts,tsx}` (happy-dom fast)
+- `browser`: `src/**/*.test.{ts,tsx}` with the browser runner (Playwright + Chromium, headless by default, slowest)
+
+You can run the full check suite by using: `gradlew :client:packages-qomponents:check`
+
+### Run a subset of tests
+
+Use these when iterating quickly on a specific test category.
+
+- Run the runtime test suite (unit + component + browser, excludes build verification) when you want fast feedback on
+  component behavior without rebuilding `dist/`: `gradlew :client:packages-qomponents:test`
+- Run unit tests only when you want the fastest feedback and no DOM simulation overhead (pure Node): `pnpm test:unit`
+- Run component tests only when you need DOM rendering via happy-dom but don't need real browser behavior:
+  `pnpm test:component`
+- Run browser tests only when validating real browser behavior (Playwright/Chromium headless): `pnpm test:browser`
+- Run browser tests with a visible browser when debugging flaky UI interactions: `pnpm test:browser:ui`
+- Watch mode for rapid iteration while editing tests or components: `pnpm test:watch`
+- Collect test coverage when you need signal on what code paths are exercised: `pnpm test:coverage`
+
+### Run build verification tests
+
+You can validate the built `dist/` output (bundles, types, assets, example app) by running:
+`gradlew :client:packages-qomponents:testBuild`
+
+## Icons
+
+Qomponents uses the `@seeqdev/icons` package for SVG icons. Icons are tree-shakeable (a.k.a. only imported icons are in the final web app bundle).
+
+The `Icon` component and icon-accepting props (like `<Button icon>`) support two formats:
+
+1. **IconDefinition objects** (recommended): Import from `@seeqdev/icons/*` sub-paths
+2. **Legacy string format**: Font Awesome class names like `"fa-solid fa-check"`
+
+```tsx
+import { Icon, Button } from '@seeqdev/qomponents';
+import { fcDelete, fcMagGlass } from '@seeqdev/icons/seeq';
+
+<Icon icon={fcDelete} />
+<Button icon={fcMagGlass} label="Search" />
+```
+
+See `client/packages/icons/README.md` for the full list of available sub-paths and how to add new Seeq icons.
+
+## Styles and theming
+
+Qomponents supports Seeq themes and dark mode. Many recent changes target visual polish, so validate styling in
+light/dark and in relevant themes before publishing.
+
+## Publishing
+
+Publishing is handled by the Gradle task. This cannot be run locally unless you have `NPM_TOKEN` set to a valid NPM
+token.
+
+```sh
+gradlew :client:packages-qomponents:npmPublish
+```
+
+Notes:
+
+- The package version is read from `client/packages/qomponents/package.json`.
+- `package.json` only publishes `dist/` (via `files`), but `README.md` is always included by npm.
+- The build produces ESM/CJS bundles, CSS, and type declarations under `dist/`, and copies icon fonts plus the
+  `example/` app into `dist/example` so consumers can run a working sample aligned to the published package.
+
+## CI publishing and version checks
+
+Publishing runs in CI. The checked-in `client/packages/qomponents/package.json` provides the base version, and the CI
+publish step will append a [prerelease](https://semver.org/#spec-item-9) suffix to distinguish published versions:
+`-beta.{10-char-sha}.YYYYMMDD`
+
+For the full internal process, see:
+
+```
+https://seeq.atlassian.net/wiki/spaces/SQ/pages/3416031265/How+To+Add+or+Modify+a+Qomponent+Seeq+Component+Library
+```
+
+## StyleX build support
+
+The build compiles component styles, token defaults, and exported themes together.
+
+Inside the monorepo, consumers compile qomponents source using the shared Rust/SWC `@seeqdev/tools/stylex` configuration.
+Named token definitions in `src/theme/<name>.stylex.ts` are directly importable from
+`@seeqdev/qomponents/theme/<name>.stylex`. Keep theme overrides in ordinary `.ts` modules and include public themes in
+the library's export graph so the publish build emits their CSS.
+
+The `@stylex;` marker in `src/styles.build.css` receives minified extracted CSS during publication.
+Published consumers use compiled JavaScript and import `@seeqdev/qomponents/styles.css`; no StyleX compiler is required.
+The source-only theme subpath is not published. Supporting external StyleX compilation of shared definitions will
+need an explicit module-identity and export contract before it is enabled.
+
+StyleX emits atomic CSS by default. Shared compiler options enable native CSS layers to coexist with existing styles;
+normal unlayered CSS still takes precedence. See [the build documentation](../tools/src/stylex/README.md) for the
+layer ordering, migration constraints and test commands. The published CSS keeps the stable `styles.css` filename.
+
+### Build artifact tests
+
+`pnpm test:build` builds once and runs both artifact checks: `build.test.ts` checks files, exports, and copied
+resources in Node/happy-dom; `build.browser.test.tsx` checks the built JavaScript and CSS in Chromium. The browser
+project intentionally has no StyleX or Tailwind compiler, so it detects missing published styles and token defaults.
+The two files share the build test configuration but need separate runtimes: happy-dom cannot validate the CSS
+cascade, and Chromium cannot run the filesystem checks.
+
+Locally themed dropdowns pass the same theme to `contentXstyle` so the portaled menu and submenus receive it:
+
+```tsx
+<ButtonWithDropdown contentXstyle={themes.topic.dark} dropdownItems={items} />
+```
+
+A theme applied to `body` is inherited by portals automatically.

package/README.md

@@ -89,22 +89,23 @@ If you're using webpack + scss be sure to include a <code>~</code> as part of th
 
 <h3>2) How do I get my Button to be green?</h3>
 
-The colors of your qomponents are controlled by the "theme". </br>
-If you do not provide a theme your qomponents will use the default blue or also known as Topic-based theme.
-Themes are applied by adding the class of the desired theme to a wrapper of your application. The theme class can
-also be applied to the body tag.
+Themes are selected with `themes[product][mode]` and applied to an application wrapper using `stylex.props`.
+Without an explicit theme, components use Topic light colors.
 
-```html
-<div class="color_analysis">... your application here</div>
-```
+```tsx
+import * as stylex from '@stylexjs/stylex';
+import { Button, themes } from '@seeqdev/qomponents';
+import '@seeqdev/qomponents/styles.css';
 
-There are 3 themes available:
+<div {...stylex.props(themes.analysis.light)}>
+  <Button label="Save" />
+</div>;
+```
 
-| Theme    | Color  | Class          | Example                |
-| :------- | :----- | :------------- | :--------------------- |
-| Topic    | blue   | color_topic    | class="color_topic"    |
-| Analysis | green  | color_analysis | class="color_analysis" |
-| DataLab  | orange | color_datalab  | class="color_datalab"  |
+Available products are `topic`, `analysis`, `datalab`, `vantage`, and `insights`; each supports `light` and `dark`.
+Use `themes.analysis.dark` for the dark Analysis theme. Selecting a compiled theme requires the StyleX runtime,
+but no consumer-side StyleX compiler. Apply the same theme to portal roots when they are outside the themed wrapper.
+The former `color_*` classes are no longer part of the published stylesheet.
 
 <h3>3) How do I use Fontawesome Icons?</h3>
 Before you can use Fontawesome icons you must install FontAwesome.

package/dist/example/{.eslintrc.js → .eslintrc.cjs}

@@ -1,4 +1,5 @@
-export default {
+module.exports = {
+  root: true,
   env: { browser: true, es2020: true },
   extends: ['eslint:recommended', 'plugin:@typescript-eslint/recommended', 'plugin:react-hooks/recommended'],
   parser: '@typescript-eslint/parser',

package/dist/example/.gitignore

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

package/dist/example/README.md

@@ -12,7 +12,9 @@ This application is built using [vite](https://vitejs.dev/).
 
 ## Installation
 
-First, be sure to install all dependencies (React, and qomponents):
+This example uses the compiled qomponents bundle next to it, without a StyleX or Tailwind compiler.
+When running from the source repository, first run `pnpm build` in the qomponents package. The example included
+in a published package already has that bundle. Then install the example's React and Vite dependencies:
 
 ```sh
 npm install

package/dist/example/package.json

@@ -11,15 +11,13 @@
   },
   "dependencies": {
     "@fortawesome/fontawesome-free": "^6.4.0",
-    "@seeqdev/qomponents": "0.0.243-beta.8c6897da6a.20260807",
-    "@tailwindcss/vite": "4.1.8",
-    "react": "18.2.0",
-    "react-dom": "18.2.0",
-    "tailwindcss": "4.1.8"
+    "@stylexjs/stylex": "0.19.1",
+    "react": "19.2.0",
+    "react-dom": "19.2.0"
   },
   "devDependencies": {
-    "@types/react": "18.0.37",
-    "@types/react-dom": "18.0.11",
+    "@types/react": "19.2.10",
+    "@types/react-dom": "19.2.3",
     "@typescript-eslint/eslint-plugin": "5.59.0",
     "@typescript-eslint/parser": "5.59.0",
     "@vitejs/plugin-react": "4.5.1",