@wpmoo/ui 0.7.0 → 0.8.0

package/ASSET_LICENSE.md

@@ -6,7 +6,7 @@ WPMoo-generated visual assets are copyright (c) 2026 WPMoo
 These assets are not licensed under the repository's MIT source code license
 unless an individual file or directory states otherwise. This includes brand
 assets, component preview images, marketing images, screenshots, generated
-artwork, and other WPMoo-owned image assets under `static/images/`.
+artwork, and other WPMoo-owned image assets under `site/static/images/`.
 
 You may view these assets as part of the Moo UI documentation and demo site.
 You may not copy, redistribute, modify, sell, sublicense, or use them in another

package/README.md

@@ -9,40 +9,37 @@
   <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg"></a>
 </p>
 
-<p align="center">
-  <strong>Bootstrap markup. shadcn feel.</strong>
-</p>
-
-<p align="center">
-  Keep your Bootstrap 5.3 HTML and behavior. Replace the stylesheet and give
-  your application a calmer, modern product interface without moving to React or
-  Tailwind.
-</p>
+<p align="center"><strong>Bootstrap markup. shadcn feel.</strong></p>
 
 <p align="center">
-  <a href="https://ui.wpmoo.org/"><strong>Explore Moo UI »</strong></a>
+  Moo UI is a Bootstrap 5.3-native component system with a restrained,
+  shadcn-inspired visual language.
 </p>
 
 <p align="center">
+  <a href="https://ui.wpmoo.org/"><strong>Explore the catalog »</strong></a> ·
   <a href="#try-it-in-30-seconds">Try it in 30 seconds</a> ·
-  <a href="https://www.npmjs.com/package/@wpmoo/ui">View on npm</a> ·
-  <a href="https://github.com/wpmoo-org/ui/issues">Report bug</a>
+  <a href="https://github.com/wpmoo-org/ui/issues">Report an issue</a>
 </p>
 
 # Moo UI
 
-Moo UI is for teams that already like Bootstrap's durability, documented
-components, and server-rendered friendliness, but want their customer portals,
-admin screens, and business applications to feel more like modern SaaS
-software.
+Moo UI preserves Bootstrap markup, variables, and JavaScript plugins wherever
+Bootstrap already provides the contract. For patterns Bootstrap does not
+provide, Moo UI adds small documented extensions, including optional ESM for
+Combobox, Context Menu, DataTable, and Sidebar.
 
-It keeps Bootstrap as the public contract: familiar classes, `data-bs-*`
-behavior, CSS variables, Sass customization, and Bootstrap JavaScript plugins.
-Moo UI changes the visual language around that contract.
+- **CSS-first.** Most components need only the stylesheet and ordinary HTML.
+- **Bootstrap owns native behavior.** Keep using Bootstrap's bundle for its
+  Dropdown, Modal, Offcanvas, Tooltip, Popover, Toast, and other plugins.
+- **Moo extends verified gaps.** Optional Moo ESM is explicit and
+  side-effect-free; importing it never scans the document automatically.
+- **Adopt all at once or gradually.** Use the full Bootstrap build or scope the
+  Moo component layer to a `.moo-ui` boundary.
 
 ## Try It in 30 Seconds
 
-Drop the stylesheet into ordinary Bootstrap markup:
+The quick demo intentionally follows the floating npm tag:
 
 ```html
 <link rel="stylesheet"
@@ -51,135 +48,154 @@ Drop the stylesheet into ordinary Bootstrap markup:
 <button type="button" class="btn btn-primary">Create workspace</button>
 ```
 
-That is the point of Moo UI: your markup still says Bootstrap, but the surface
-feels quieter, sharper, and more product-ready.
+`moo-ui.css` is a complete Bootstrap CSS build with Moo UI defaults. Use it
+instead of another Bootstrap stylesheet, not in addition to one.
 
-## Install
+## Runtime Ownership
+
+| Surface | Runtime owner | What to load |
+| --- | --- | --- |
+| Static HTML and CSS components | Browser + Bootstrap markup | `moo-ui.css`, or Bootstrap CSS followed by scoped `moo.css` |
+| Dropdown, Modal, Offcanvas, Tooltip, Popover, Toast, and other Bootstrap plugins | Bootstrap | Bootstrap's JavaScript bundle and documented initialization |
+| Combobox | Optional Moo ESM | `@wpmoo/ui/combobox.js`, then explicit initialization |
+| Context Menu pointer and keyboard invocation | Optional Moo ESM, composed with Bootstrap Dropdown | `@wpmoo/ui/context-menu.js`, then explicit initialization |
+| DataTable sorting, filtering, selection, pagination, and responsive card sync | Optional Moo ESM, composed with Bootstrap Table and controls | `@wpmoo/ui/datatable.js`, then explicit initialization |
+| Sidebar state and responsive coordination | Optional Moo ESM, composed with Bootstrap plugins | `@wpmoo/ui/sidebar.js`, then explicit initialization |
+
+Moo UI does not replace Bootstrap plugins and does not publish a mandatory
+aggregate JavaScript runtime.
 
-Use the published package when a bundler owns your build:
+## Install
 
 ```bash
-npm install @wpmoo/ui
+npm install @wpmoo/ui bootstrap
 ```
 
+### Full replacement
+
+Use the complete Moo UI Bootstrap build instead of Bootstrap's stylesheet:
+
 ```js
 import "@wpmoo/ui/moo-ui.css";
+import "bootstrap/dist/js/bootstrap.bundle.min.js"; // only when plugins are used
 ```
 
-If a page uses Bootstrap plugins such as Dropdown, Tooltip, Popover, Modal,
-Toast, or Offcanvas, load Bootstrap's JavaScript bundle separately through your
-application. Tooltip and Popover also need the initialization Bootstrap
-documents for those plugins.
+### Scoped gradual adoption
+
+Keep the existing Bootstrap stylesheet, load the scoped Moo layer after it, and
+wrap only the area being migrated:
+
+```js
+import "bootstrap/dist/css/bootstrap.min.css";
+import "@wpmoo/ui/moo.css";
+import "bootstrap/dist/js/bootstrap.bundle.min.js"; // only when plugins are used
+```
+
+```html
+<div class="moo-ui">
+  <button type="button" class="btn btn-primary">Create workspace</button>
+</div>
+```
+
+### Optional Moo ESM
+
+Initialize only the documented behavior gaps you use:
+
+```js
+import Combobox from "@wpmoo/ui/combobox.js";
+import ContextMenu from "@wpmoo/ui/context-menu.js";
+import DataTable from "@wpmoo/ui/datatable.js";
+import Sidebar from "@wpmoo/ui/sidebar.js";
+
+Combobox.getOrCreateInstance(document.querySelector(".combobox"));
+ContextMenu.getOrCreateInstance(document.querySelector(".context-menu"));
+DataTable.getOrCreateInstance(document.querySelector(".datatable"));
+Sidebar.getOrCreateInstance(document.querySelector('[data-slot="sidebar-wrapper"]'));
+```
+
+See the [Installation guide](https://ui.wpmoo.org/installation/) for CDN
+recipes, load order, and troubleshooting.
 
 ## Choose an Adoption Path
 
-| Situation | Use | Contract |
-| --- | --- | --- |
-| New page or whole application | `moo-ui.css` | Complete Bootstrap CSS build with Moo UI defaults; use it instead of your existing Bootstrap stylesheet. |
-| Gradual adoption inside an existing Bootstrap app | `moo.css` | Scoped Moo component layer under a `.moo-ui` boundary for gradual adoption inside an existing Bootstrap app. |
+| Situation | Recommended path |
+| --- | --- |
+| New page or whole application | Replace Bootstrap CSS with `moo-ui.css`. |
+| Existing Bootstrap application | Load `moo.css` after Bootstrap CSS and add `.moo-ui` around migrated regions. |
+| Static page with no interactive plugins | Load CSS only. |
+| Page using Bootstrap plugins | Keep Bootstrap's bundle and its documented initialization. |
+| Page using Combobox, Context Menu, DataTable, or Sidebar | Add only the corresponding optional Moo ESM module. |
+
+## Public Package Surface
+
+`@wpmoo/ui` exports exactly these public entrypoints:
+
+| Export | Purpose |
+| --- | --- |
+| `@wpmoo/ui/moo-ui.css` | Full expanded CSS build |
+| `@wpmoo/ui/moo-ui.min.css` | Full minified CSS build |
+| `@wpmoo/ui/moo.css` | Scoped expanded component layer for `.moo-ui` |
+| `@wpmoo/ui/moo.min.css` | Scoped minified component layer |
+| `@wpmoo/ui/combobox.js` | Optional Combobox ESM lifecycle |
+| `@wpmoo/ui/context-menu.js` | Optional Context Menu ESM lifecycle |
+| `@wpmoo/ui/datatable.js` | Optional DataTable ESM lifecycle |
+| `@wpmoo/ui/sidebar.js` | Optional Sidebar ESM lifecycle |
+| `@wpmoo/ui/certification.json` | Versioned support/evidence manifest |
+| `@wpmoo/ui/package.json` | Package metadata |
+
+The tarball also contains `README.md`, `LICENSE`, and `ASSET_LICENSE.md`. It
+does not publish catalog templates, preview artwork, catalog JavaScript, SCSS
+source, or a Sass facade. Internal Sass partials and
+Jinja macros are repository build tools, not npm APIs.
 
 ## Why Bootstrap Teams Try It
 
-- **No frontend rewrite.** Keep server-rendered HTML, Bootstrap classes, and
-  the component behavior your team already knows.
-- **Modern product rhythm.** Buttons, forms, overlays, navigation, data
-  display, and app shells are tuned toward a restrained shadcn-inspired feel.
-- **Inspectable examples.** The catalog is static HTML. Every component page
-  shows rendered examples and copyable markup.
-- **Bootstrap-native customization.** Moo UI uses Bootstrap Sass knobs and
-  `--bs-*` variables wherever Bootstrap can express the need, adding Moo-owned
-  tokens only for gaps Bootstrap does not model.
-- **Practical migration surface.** Start with one page, one scoped area, or a
-  full stylesheet replacement after visual review.
-
-## Philosophy
-
-- **Bootstrap is the contract.** Moo UI keeps Bootstrap markup, documented
-  behavior, Sass knobs, and `--bs-*` variables wherever Bootstrap can express
-  the need.
-- **shadcn is the feeling.** Moo UI studies restraint, rhythm, and product UI
-  sensibility without adopting React, Tailwind, Radix, or shadcn source.
-- **HTML stays first-class.** The catalog is static, inspectable, and friendly
-  to server-rendered applications.
-- **Extensions stay honest.** Moo-owned classes and behavior are added only
-  when Bootstrap has no native component contract for the pattern.
-
-## What Is Included
-
-The live catalog is the source of truth for current coverage:
-
-- [Components](https://ui.wpmoo.org/components/) for actions, forms,
-  data display, feedback, disclosure, overlays, and navigation.
-- [Blocks](https://ui.wpmoo.org/blocks/) for composed application
-  surfaces such as sidebar layouts.
-- A static documentation site that can be inspected without a client-side app
-  runtime.
-
-Representative components include Button, Field, Table, Dialog, Toast, Sheet,
-and Sidebar. More components are being added as the catalog roadmap continues.
+- Keep server-rendered HTML, Bootstrap classes, and familiar plugin behavior.
+- Apply a restrained product rhythm to forms, overlays, navigation, data
+  display, and application shells.
+- Inspect static rendered examples and copy the resulting HTML contracts.
+- Start with one scoped region or replace the full stylesheet after review.
+
+Representative components include Button, Field, Table, DataTable, Dialog,
+Toast, Sheet, Combobox, Context Menu, and Sidebar. Browse the [component catalog](https://ui.wpmoo.org/components/)
+and composed [blocks](https://ui.wpmoo.org/blocks/).
 
 ## Designed, Not Just Restyled
 
-Moo UI uses original sketch-style previews to show the thinking behind each
-primitive: states, spacing, hierarchy, and the product UI feeling Bootstrap
-projects often need. The README wraps a few of those transparent assets in
-theme-aware surfaces so they stay legible on GitHub.
+The README uses original WPMoo preview artwork stored under
+`site/static/images/`; those files are source assets for the public catalog and
+are not part of the npm package.
 
 <p align="center">
-  <a href="https://ui.wpmoo.org/components/button/">
-    <picture>
-      <source media="(prefers-color-scheme: dark)" srcset="static/images/readme/button-dark.svg">
-      <img src="static/images/readme/button-light.svg" alt="Button preview" width="31%">
-    </picture>
-  </a>
-  <a href="https://ui.wpmoo.org/components/dialog/">
-    <picture>
-      <source media="(prefers-color-scheme: dark)" srcset="static/images/readme/dialog-dark.svg">
-      <img src="static/images/readme/dialog-light.svg" alt="Dialog preview" width="31%">
-    </picture>
-  </a>
-  <a href="https://ui.wpmoo.org/components/sidebar/">
-    <picture>
-      <source media="(prefers-color-scheme: dark)" srcset="static/images/readme/sidebar-dark.svg">
-      <img src="static/images/readme/sidebar-light.svg" alt="Sidebar preview" width="31%">
-    </picture>
-  </a>
-  <a href="https://ui.wpmoo.org/components/toast/">
-    <picture>
-      <source media="(prefers-color-scheme: dark)" srcset="static/images/readme/toast-dark.svg">
-      <img src="static/images/readme/toast-light.svg" alt="Toast preview" width="31%">
-    </picture>
-  </a>
-  <a href="https://ui.wpmoo.org/components/sheet/">
-    <picture>
-      <source media="(prefers-color-scheme: dark)" srcset="static/images/readme/sheet-dark.svg">
-      <img src="static/images/readme/sheet-light.svg" alt="Sheet preview" width="31%">
-    </picture>
-  </a>
-  <a href="https://ui.wpmoo.org/components/input/">
-    <picture>
-      <source media="(prefers-color-scheme: dark)" srcset="static/images/readme/input-dark.svg">
-      <img src="static/images/readme/input-light.svg" alt="Input preview" width="31%">
-    </picture>
-  </a>
+  <a href="https://ui.wpmoo.org/components/button/"><picture><source media="(prefers-color-scheme: dark)" srcset="https://ui.wpmoo.org/assets/images/readme/button-dark.svg"><img src="https://ui.wpmoo.org/assets/images/readme/button-light.svg" alt="Button preview" width="31%"></picture></a>
+  <a href="https://ui.wpmoo.org/components/dialog/"><picture><source media="(prefers-color-scheme: dark)" srcset="https://ui.wpmoo.org/assets/images/readme/dialog-dark.svg"><img src="https://ui.wpmoo.org/assets/images/readme/dialog-light.svg" alt="Dialog preview" width="31%"></picture></a>
+  <a href="https://ui.wpmoo.org/components/sidebar/"><picture><source media="(prefers-color-scheme: dark)" srcset="https://ui.wpmoo.org/assets/images/readme/sidebar-dark.svg"><img src="https://ui.wpmoo.org/assets/images/readme/sidebar-light.svg" alt="Sidebar preview" width="31%"></picture></a>
 </p>
 
-<p align="center">
-  <a href="https://ui.wpmoo.org/components/">Browse the full catalog →</a>
-</p>
+## Status And Support
 
-## Package Boundaries
+Moo UI is in the `0.x` series. Current package: `@wpmoo/ui@0.8.0`. The
+package's certification manifest currently has `preview` status; catalog
+availability is WPMoo-maintained preview evidence, not independent or
+accredited certification. Read [Support & Evidence](https://ui.wpmoo.org/support/)
+for the Bootstrap range, browser policy, maturity definitions, limitations, and
+release evidence. Complete release notes are on
+[GitHub Releases](https://github.com/wpmoo-org/ui/releases).
 
-The npm package distributes compiled CSS and license/notice files. It does not
-ship the catalog's generated preview images, Jinja templates, Sass source, or
-Moo-owned catalog JavaScript.
+## Contributing
 
-The source repository contains the static catalog, component templates, build
-tooling, tests, and documentation.
+Small documentation corrections, reduced reproductions, accessibility checks,
+and bounded component improvements are welcome. Start with
+[`CONTRIBUTING.md`](CONTRIBUTING.md), choose an
+[issue type](https://github.com/wpmoo-org/ui/issues/new/choose), and review the
+[Code of Conduct](CODE_OF_CONDUCT.md) and [security policy](SECURITY.md).
 
-## Development
+## Repository Layout And Development
 
-The catalog is intentionally small-tool friendly:
+Moo UI Core is published from the repository root. Core source and package
+outputs live outside `site/`; `dist/` is the package build. The `site/` tree
+owns ui.wpmoo.org documentation, catalog chrome, public metadata, and protected
+preview artwork; it builds to `site-dist/`.
 
 ```bash
 .venv/bin/python build.py
@@ -187,23 +203,11 @@ The catalog is intentionally small-tool friendly:
 .venv/bin/python -m unittest discover -s tests -v
 ```
 
-For developers who prefer npm scripts, the package also exposes:
-
-```bash
-npm run build
-npm run dev
-npm test
-```
-
-Browse the local catalog at `http://localhost:4173/` when `dev.py` is running.
+Browse the local catalog at `http://localhost:4173/` while `dev.py` runs.
 
 ## Licensing
 
-Moo UI source code is licensed under the MIT License by WPMoo (`wpmoo.org`).
-
-WPMoo-generated visual assets, including image assets under `static/images/`,
-are not covered by the MIT source code license and remain copyright WPMoo, all
-rights reserved.
-
-Vendored third-party material keeps its original license and attribution. See
+Moo UI source code is MIT licensed. WPMoo-generated visual assets under
+`site/static/images/` remain separately protected as described in
+`ASSET_LICENSE.md`. Vendored dependencies retain their original licenses; see
 `LICENSE`, `ASSET_LICENSE.md`, and `THIRD_PARTY_NOTICES.md`.

package/certification.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "0.1",
   "status": "preview",
-  "coreVersion": "0.7.0",
+  "coreVersion": "0.8.0",
   "bootstrap": {
     "canonicalVersion": "5.3.3",
     "targetRange": ">=5.3.0 <5.4",
@@ -22,7 +22,9 @@
     ],
     "esm": [
       "./combobox.js",
-      "./sidebar.js"
+      "./sidebar.js",
+      "./context-menu.js",
+      "./datatable.js"
     ],
     "sass": []
   },