Milestone3m [WiP]

.gitignore

@@ -9,3 +9,4 @@ docs/api
 examples/storybook
 .history/
 docs/form-examples/solid-ui.js
+.tsbuildinfo

README.md

@@ -17,9 +17,12 @@ See [Forms introduction](./docs/FormsReadme.md) for UI vocabulary implementation
 - [Use Directly in Browser](#use-directly-in-a-browser)
   - [UMD Bundle](#umd-bundle-global-variable)
   - [ESM Bundle](#esm-bundle-import-as-module)
-- [Development](#development-new-components)
+- [Web Components](#web-components)
+  - [solid-ui-header](#solid-ui-header)
+- [Development](#development)
 - [Testing](#adding-tests)
 - [Further Documentation](#further-documentation)
+- [Generative AI usage](#generative-ai-usage)
 
 
 ## Getting started
@@ -253,7 +256,46 @@ Use import maps for cleaner module specifiers:
 </html>
 ```
 
-### Development new components
+## Web Components
+
+solid-ui ships self-contained Lit-based custom elements as subpath exports. Each component is independently importable, registers its custom element on import, and ships its own styles encapsulated in a Shadow DOM.
+
+> Component UMD bundles do not export a shared global like `window.UI`. They only register the custom element on import, while the legacy main bundle still provides the `UI` global.
+
+### solid-ui-header
+
+A header bar with branding, auth state (logged-out / logged-in), an account dropdown, and a desktop-only help menu.
+
+**Subpath export:** `solid-ui/components/header`
+
+```typescript
+import { Header } from 'solid-ui/components/header'
+import type { HeaderMenuItem, HeaderAccountMenuItem, HeaderAuthState } from 'solid-ui/components/header'
+```
+
+Importing this module automatically registers `<solid-ui-header>` as a custom element. See [src/v2/components/header/README.md](src/v2/components/header/README.md) for the full API reference and usage examples.
+
+### Component build pipeline
+
+Web components use a two-stage build to produce a clean public layout without exposing internal source paths:
+
+1. **webpack** (`npm run build-dist`) bundles each component entrypoint and emits the runtime files to `dist/components/<name>/index.js` and `dist/components/<name>/index.esm.js`.
+2. **tsc** (`npm run build-js`) emits declaration files mirroring the source tree, so they land at `dist/v2/components/<name>/index.d.ts`.
+3. **`scripts/build-component-dts.mjs`** (runs automatically after tsc as part of `postbuild-js`) writes a thin re-export wrapper at `dist/components/<name>/index.d.ts`, bridging the tsc output to the public package location.
+
+This keeps the `package.json` subpath export fully aligned:
+
+```json
+"./components/header": {
+  "types":   "./dist/components/header/index.d.ts",
+  "import":  "./dist/components/header/index.esm.js",
+  "require": "./dist/components/header/index.js"
+}
+```
+
+Consumers never see the internal `v2` path; it is an implementation detail of the source tree.
+
+## Development
 
 When developing a component in solid-ui you can test it in isolation using storybook
 
@@ -286,3 +328,28 @@ The following document gives guidance on how to add and perform testing in solid
 ## Further documentation
 
 - [Some code know-how](https://github.com/SolidOS/solidos/wiki/2.-Solid-UI-know-how)
+
+## Generative AI usage
+The SolidOS team is using GitHub Copilot integrated in Visual Studio Code. 
+We have added comments in the code to make it explicit which parts are 100% written by AI. 
+
+### Prompt usage history:
+
+* Raptor mini: If I want to make the header a web component with a self contained CSS which only consumes CSS variables from a theme, how would I do this? 
+
+* Raptor mini: Go ahead and create a header web component, for backward compatibility keep the current code too.
+In the new header component I need to be flexible and receive from consumer - the layout (mobile or desktop) and the theme (light or dark) and its according CSS variables for light to dark.
+
+* Raptor mini: Propose code. how about webpack config for distribution?
+
+* Raptor mini: pls add a readme in the component documenting it usage and test and all
+
+* Raptor mini: the helpMenuList should be menu items inside the help icon drop down menu
+
+* Raptor mini: When I am not logged in I want the header to display: Log in button and Sign Up button.
+When the user is logged in, there is only one button, a drop down button called Accounts. The icon of the button is the avatar of the profile and it displays a list of available accounts of the user.
+I want this all to be presented flexible in the component.
+
+* Claude Sonnet 4.6: create a LitElement also for the signupButton in the SignupButton.ts based on the signup.js code and wire it into the header like you did the loginButton.
+
+* Raptor mini: when we are on layout mobile we do not want to display the help menu at all.

__mocks__/styleMock.js

@@ -0,0 +1,2 @@
+// Jest mock for CSS imports
+module.exports = {}

babel.config.mjs

@@ -5,7 +5,7 @@ export default {
         browsers: ['> 1%', 'last 3 versions', 'not dead']
       }
     }],
-    '@babel/preset-typescript',
+    ['@babel/preset-typescript', { allowDeclareFields: true }],
   ],
   plugins: [
     '@babel/plugin-transform-runtime'

jest.config.mjs

@@ -11,9 +11,12 @@ export default {
     '^.+\\.(mjs|[tj]sx?)$': ['babel-jest', { configFile: './babel.config.mjs' }],
   },
   transformIgnorePatterns: [
-    '<rootDir>/node_modules/(?!(lit-html|@noble/curves|@noble/hashes|@exodus/bytes|uuid|jsdom|parse5|@asamuzakjp/css-color|@csstools)/)',
+    '<rootDir>/node_modules/(?!(lit|lit-html|lit-element|@lit|@lit-labs|@lit-labs/ssr-dom-shim|@lit/reactive-element|@noble/curves|@noble/hashes|@exodus/bytes|uuid|jsdom|parse5|@asamuzakjp/css-color|@csstools)/)',
   ],
   setupFilesAfterEnv: ['./test/helpers/setup.ts'],
+  moduleNameMapper: {
+    '^.+\\.css$': '<rootDir>/__mocks__/styleMock.js'
+  },
   testMatch: ['**/?(*.)+(spec|test).[tj]s?(x)'],
   roots: ['<rootDir>/src', '<rootDir>/test', '<rootDir>/__mocks__'],
 }