bitboss-ui 2.1.135 → 3.0.0-alpha.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BitBoss
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -28,13 +28,14 @@ Published artifacts are **`dist/`** (ESM JavaScript, `.d.ts`, and **`index.css`*
 | `useQueue`                    | Simple async task queue.                                  |
 | `useToast`                    | Toast notifications API.                                  |
 
-### Base\* components (primitives)
+### Base\* components (primitives) _(reference-only - prefer `Bb*` equivalents for consumer code)_
 
 Headless or low-level pieces used inside **Bb\*** wrappers or your own compositions:
 
-- **Actions:** `BaseButton`
+- **Actions:** `BbBaseButton`
 - **Text & numbers:** `BaseTextInput`, `BaseTextarea`, `BaseNumberInput`, `BaseTag`
 - **Choice:** `BaseCheckbox`, `BaseCheckboxGroup`, `BaseRadio`, `BaseRadioGroup`, `BaseSwitch`, `BaseSwitchGroup`, `BaseSlider`, `BaseRating`
+- **Choice glyphs (presentational SVGs):** `BbBaseCheckboxIcon`, `BbBaseRadioIcon`, `BbBaseSwitchIcon`
 - **Rich inputs:** `BaseSelect`, `BaseColorInput`, `BaseDatePicker`, `BaseDatePickerInput`
 - **Layout / chrome:** `BaseInputContainer`, `BaseDialog`
 
@@ -42,17 +43,16 @@ Headless or low-level pieces used inside **Bb\*** wrappers or your own compositi
 
 Product-ready components with labels, hints, errors, and consistent styling:
 
-- **Forms & actions:** `BbTextInput`, `BbTextarea`, `BbNumberInput`, `BbSelect`, `BbCheckbox`, `BbCheckboxGroup`, `BbRadio`, `BbRadioGroup`, `BbSwitch`, `BbSwitchGroup`, `BbSlider`, `BbRating`, `BbColorInput`, `BbDatePickerInput`, `BbButton`, `BbChip`, `BbTag`, `BbDropdown`, `BbDropdownButton`
+- **Forms & actions:** `BbTextInput`, `BbTextarea`, `BbNumberInput`, `BbSelect`, `BbCheckbox`, `BbCheckboxGroup`, `BbRadio`, `BbRadioGroup`, `BbSwitch`, `BbSwitchGroup`, `BbSlider`, `BbRating`, `BbColorInput`, `BbDatePickerInput`, `BbButton`, `BbBadge`, `BbIndicator`, `BbTag`, `BbDropdown`, `BbDropdownButton`
 - **Feedback:** `BbAlert`, `BbProgress`, `BbSpinner`, `BbToast`, `BbTooltip`
-- **Layout & navigation:** `BbAccordion`, `BbCollapsible`, `BbTab`, `BbBreadcrumbs`, `BbPagination`, `BbRows`, `BbRatio`, `BbSmoothHeight`
+- **Layout & navigation:** `BbAccordion`, `BbCollapsible`, `BbTab`, `BbBreadcrumbs`, `BbPagination`,`BbSmoothHeight`
 - **Overlays & panels:** `BbDialog`, `BbConfirm`, `BbConfirmPortal`, `BbOffCanvas`, `BbPopover`
 - **Data:** `BbTable`, `BbTree`
 - **Media & files:** `BbAvatar`, `BbDropzone`, `BbIcon`
-- **Utilities:** `BbIntersection`
 
-### Shared input shells
+### Shared input shells _(internal layout primitives - not for direct consumer use)_
 
-- **`CommonInputInnerContainer`**, **`CommonInputOuterContainer`** — layout primitives for building inputs that align with BitBoss spacing, icons, and clear buttons.
+- **`CommonInputWrapper`** — the internal input-chrome primitive (label, prepend/append, prefix/suffix, clear button, spacing) that every `Bb*` input composes. Not exported; use the full public inputs (`BbTextInput`, `BbSelect`, …).
 
 ### Exported component types
 
@@ -66,38 +66,53 @@ For most **Base\*** and **Bb\*** components, the package exports matching **prop
 
 - [BitBoss UI documentation](https://ui-components-docs.vercel.app/) — site with guides and API reference.
 
----
+**For AI coding agents:**
 
-## BitBoss
+The same knowledge base the npm package ships is served publicly over a CDN, so
+an agent can read it before anything is installed. `@alpha` tracks the latest
+v3 prerelease; pin an exact version (`bitboss-ui@3.0.0-alpha.4`) for stable
+links.
 
-This package is developed and maintained by [BitBoss](https://www.bitboss.it/), a software house based in Turin, Italy.
+- [Core knowledge base](https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/llms-medium.txt) (~74 KB) — **start here if you can only fetch one file.** Hard rules, setup, component picker, design language, and the full component catalogue.
+- [Index](https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/llms.txt) (~17 KB) — link index into every document.
+- [components.json](https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/components.json) — machine-readable API surface, for programmatic validation.
+- [Complete knowledge base](https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/llms-full.txt) (~2.9 MB) — everything concatenated. Bulk ingestion only; too large to prompt with.
 
-- [BitBoss — homepage](https://www.bitboss.it/)
-- [BitBoss Developers](https://developers.bitboss.it/) — community and developer-facing resources
+Already installed? Prefer the local copy under `node_modules/bitboss-ui/dist/ai/`,
+run `npx bitboss-ui ai-init` to write agent pointers, and
+`npx bitboss-ui check` to validate markup against the installed version.
 
 ---
 
-## Requirements
+## BitBoss
 
-- **Vue** `^3.5.12` (peer dependency).
-- **`@inertiajs/vue3`** — optional peer. Install it only if you use Inertia-specific helpers or components that expect an Inertia app; Nuxt and plain Vue apps can omit it.
+This package is developed and maintained by [BitBoss](https://www.bitboss.it/), a software house based in Turin, Italy.
+
+- [BitBoss — homepage](https://www.bitboss.it/)
 
 ---
 
 ## Installation
 
+**v3 is a prerelease: the `@alpha` tag is required.** A bare
+`npm install bitboss-ui` resolves to the v2 line, which has no build plugin and
+no `dist/ai` knowledge base — if you are following the v3 docs, that install
+will not work.
+
 ```bash
-npm install bitboss-ui
+npm install bitboss-ui@alpha
 ```
 
 ```bash
-pnpm add bitboss-ui
+pnpm add bitboss-ui@alpha
 ```
 
 ```bash
-yarn add bitboss-ui
+yarn add bitboss-ui@alpha
 ```
 
+Verify with `npm ls bitboss-ui` — it must report `3.0.0-alpha.*`.
+
 ---
 
 ## Quick start
@@ -120,16 +135,233 @@ import 'bitboss-ui/styles.css';
 
 Use this once in your app entry (or in Nuxt/Vite global CSS) so components match the intended look and layout.
 
+### Vite plugin
+
+Use the Vite export to enable icon virtual modules and typed registry integration:
+
+```ts
+import { defineConfig } from 'vite';
+import vue from '@vitejs/plugin-vue';
+import { bitbossUi } from 'bitboss-ui/vite';
+
+export default defineConfig({
+	plugins: [
+		vue(),
+		bitbossUi({
+			iconDir: './src/assets/icons',
+		}),
+	],
+});
+```
+
+### Nuxt module
+
+```ts
+export default defineNuxtConfig({
+	modules: ['bitboss-ui/nuxt'],
+	bitboss: {
+		iconDir: './assets/icons',
+	},
+	css: ['bitboss-ui/styles.css'],
+});
+```
+
+## AI / coding-assistant support
+
+This package ships a machine-readable knowledge base alongside the compiled library. It is designed for **any** coding agent (Cursor, Claude Code, Copilot, Windsurf, Codex, …) — not a single vendor.
+
+**Start here (tiny hop map):** `node_modules/bitboss-ui/dist/ai/guides/ai-router.md`
+
+Then the catalogue: `node_modules/bitboss-ui/dist/ai/index.md`
+
+### One-command consumer kickstart
+
+After installing `bitboss-ui` in an app:
+
+```bash
+npx bitboss-ui ai-init
+# same as: npx bitboss-ui ai-init --update
+```
+
+Idempotently writes:
+
+| File                                    | Harness                  |
+| --------------------------------------- | ------------------------ |
+| `AGENTS.md` (marker-delimited fragment) | Cursor / Codex / generic |
+| `.cursor/rules/bitboss-ui.mdc`          | Cursor                   |
+| `.github/copilot-instructions.md`       | GitHub Copilot           |
+| `.claude/skills/bitboss-ui/SKILL.md`    | Claude Code              |
+| `.windsurf/rules/bitboss-ui.md`         | Windsurf                 |
+
+Re-run after upgrading `bitboss-ui` so versioned pointers stay fresh.
+
+### MCP server (optional)
+
+The kickstart above writes static pointer files. Add `--mcp` to also register a
+live [Model Context Protocol](https://modelcontextprotocol.io) server so agents
+can **query** the knowledge base (search components, read a contract, validate
+markup) instead of reading files blind:
+
+```bash
+npx bitboss-ui ai-init --mcp
+```
+
+The agent harness launches the server itself (`npx bitboss-ui mcp`) on demand —
+you never run it by hand. `--mcp` merges the server entry into each harness's
+own config (never overwriting other servers you've registered), and each write
+is idempotent:
+
+| File                                  | Harness           | Scope                      |
+| ------------------------------------- | ----------------- | -------------------------- |
+| `.mcp.json`                           | Claude Code       | project                    |
+| `.cursor/mcp.json`                    | Cursor            | project                    |
+| `.vscode/mcp.json`                    | VS Code / Copilot | project                    |
+| `~/.codeium/windsurf/mcp_config.json` | Windsurf          | **global (whole machine)** |
+
+> **Windsurf is global.** Cascade only reads one config in your home directory —
+> it has no per-project scope — so registering it affects **every** project on
+> your machine, not just this one. That is why the dev-server auto-registration
+> below deliberately skips Windsurf; only the explicit `ai-init --mcp` command
+> writes it.
+
+**Zero-command option (dev server):** instead of running `ai-init --mcp`, pass
+`mcp: true` to the Vite/Nuxt plugin and the dev server registers the
+project-scoped harnesses (Claude Code, Cursor, VS Code) automatically on boot —
+idempotent, and it leaves Windsurf's global config alone:
+
+```ts
+bitbossUi({ iconDir: './assets/icons', mcp: true });
+```
+
+Restart your agent harness once after either path so it picks up the new server.
+
+### ESLint plugin
+
+`bitboss-ui/eslint-plugin` flags unknown props, unknown `v-model`s, and
+removed/renamed props on `Bb*` components **live in the editor** — the same
+manifest checks as `bitboss-ui check`, so editor, CLI, and CI agree. It reuses
+your existing `vue-eslint-parser` setup (from `eslint-plugin-vue`) and no-ops on
+non-Vue files.
+
+**Needs the TypeScript parser wired for `.ts` and `.vue`.** This library is
+TS-first — recipes ship `<script setup lang="ts">`, some with `generic="T"` —
+and without the two blocks below, `vue-eslint-parser` throws a `Parsing error`
+on those files. A parsing error means **no rule runs on that file at all**,
+`no-unknown-attributes` included, so the safety net silently goes dark on
+exactly the files it matters most for.
+
+```bash
+npm i -D @typescript-eslint/parser
+```
+
+```js
+// eslint.config.js (flat config)
+import vue from 'eslint-plugin-vue';
+import tsParser from '@typescript-eslint/parser';
+import bitbossUi from 'bitboss-ui/eslint-plugin';
+
+export default [
+	...vue.configs['flat/recommended'],
+	{
+		files: ['**/*.ts'],
+		languageOptions: { parser: tsParser },
+	},
+	{
+		files: ['**/*.vue'],
+		languageOptions: { parserOptions: { parser: tsParser } },
+	},
+	...bitbossUi.configs.recommended, // enables no-unknown-attributes on **/*.vue
+];
+```
+
+**It also migrates v2 → v3 with `eslint --fix`.** Deprecated props are rewritten
+in place — the rule is a codemod, not just a linter:
+
+| You wrote                                 | `--fix` produces                         | Kind                      |
+| ----------------------------------------- | ---------------------------------------- | ------------------------- |
+| `<BbIcon type="star" />`                  | `<BbIcon icon="star" />`                 | rename                    |
+| `<BbTable :allow-select-all="x" />`       | `<BbTable :disable-select-all="!(x)" />` | polarity inversion        |
+| `<BbSelect allow-writing="not-mobile" />` | `<BbSelect disable-writing="mobile" />`  | rename + value remap      |
+| `<BbToast placement="top-end" />`         | `<BbToast position="top-right" />`       | value map                 |
+| `<BbPopover show-arrow />`                | `<BbPopover />`                          | removed & inert → deleted |
+| `<BbBadge content="5" />`                 | _(unchanged — reported)_                 | needs a slot: manual      |
+
+The fixer is conservative: it only rewrites when the transform is provably
+correct (and never toward a name that isn't a real prop), so structural
+migrations — a value that must move to a slot, directive, or CSS — are reported
+with a migration-guide link but left for you. Run `eslint --fix`, then the
+remaining reports are exactly the by-hand cases.
+
+Every real HTML attribute (plus `aria-*` / `data-*`) falls through untouched, so
+attribute inheritance is never flagged. Escape hatches when you do need one:
+
+- standard `<!-- eslint-disable-next-line bitboss-ui/no-unknown-attributes -->`
+  (works via `eslint-plugin-vue`'s comment directives);
+- rule options — `allowAttributes: string[]` and `allowComponents: string[]`:
+
+```js
+{
+	rules: {
+		'bitboss-ui/no-unknown-attributes': [
+			'error',
+			{ allowAttributes: ['my-x-attr'], allowComponents: ['BbCustom'] },
+		],
+	},
+}
+```
+
+A standard `llms.txt` discovery file is also published at:
+
+- `node_modules/bitboss-ui/llms.txt` — package-root discovery file
+- `node_modules/bitboss-ui/dist/llms.txt` — dist-level copy
+
+### Knowledge-base layout
+
+| Path                                  | Contents                                  |
+| ------------------------------------- | ----------------------------------------- |
+| `dist/ai/guides/ai-router.md`         | **Start here** — which file to open next  |
+| `dist/ai/index.md`                    | Full catalogue + agent rules              |
+| `dist/ai/components.json`             | Machine-readable API (props/events/slots) |
+| `dist/ai/<ComponentName>.md`          | Guide-first contract per component        |
+| `dist/ai/composables/<name>.md`       | Composable docs                           |
+| `dist/ai/guides/agent-contract.md`    | Mandatory agent rules                     |
+| `dist/ai/guides/*-playbook.md`        | Coherence / fetch / options / inline-edit |
+| `dist/ai/guides/migration/`           | v2 → v3 upgrade corpus                    |
+| `dist/ai/recipes/{vue,nuxt,inertia}/` | Page-level assemblies (11 × 3)            |
+
+### Package exports
+
+```ts
+// catalogue entry
+import 'bitboss-ui/ai';
+// or resolve concrete files:
+// bitboss-ui/ai/components.json
+// bitboss-ui/ai/guides/ai-router.md
+```
+
+Agents can also read paths under `node_modules/bitboss-ui/dist/ai/` directly.
+
 ## Local development (this repository)
 
 Clone the repo, install dependencies, then:
 
-| Command            | Purpose                            |
-| ------------------ | ---------------------------------- |
-| `npm run dev`      | Vite playground app                |
-| `npm run build`    | Library build (`dist/`)            |
-| `npm run docs:dev` | Documentation site (VitePress)     |
-| `npm run lint`     | ESLint + Stylelint (as configured) |
+| Command                 | Purpose                                         |
+| ----------------------- | ----------------------------------------------- |
+| `npm run dev`           | Vite playground app                             |
+| `npm run build`         | Library build (`dist/`) + regenerates `dist/ai` |
+| `npm run generate-docs` | Regenerate AI knowledge base only               |
+| `npm run check:docs`    | Strict docs / drift gate                        |
+| `npm run lint`          | ESLint + Stylelint                              |
+
+Maintainer authoring doctrine (repo-only): [`ai/authoring/authoring-doctrine.md`](ai/authoring/authoring-doctrine.md).
+
+Branch model, commit convention, gates and the release flow: [`CONTRIBUTING.md`](CONTRIBUTING.md).
+
+---
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).
 
 ---
 
@@ -138,6 +370,24 @@ Clone the repo, install dependencies, then:
 - **Usage and APIs:** see the [documentation](https://ui-components-docs.vercel.app/).
 - **Company / licensing / commercial:** [BitBoss](https://www.bitboss.it/).
 
+### Reporting a bug
+
+The source repository is private while v3 is in development, so there is no
+public issue tracker yet. **Report bugs by email to
+[dev@bitboss.it](mailto:dev@bitboss.it)** — that address is the `bugs` contact
+in `package.json`, so `npm bugs bitboss-ui` opens it too.
+
+To make a report actionable, include:
+
+- the `bitboss-ui` version (`npm ls bitboss-ui`) and your platform — plain Vue,
+  Nuxt, or Inertia
+- whether it reproduces in dev, in a production build, or only under SSR
+- the smallest component snippet that shows it
+
+v3 ships as a prerelease (`npm i bitboss-ui@alpha`). Expect breaking changes
+between alphas; each one is recorded in the migration guides under
+[`ai/guides/migration/`](ai/guides/migration/).
+
 ---
 
 ## Trademark