@saasicat/ui-vue 1.0.0-rc.2 → 1.0.0-rc.20

package/README.md

@@ -1,26 +1,78 @@
 # @saasicat/ui-vue
 
+## What this is
+
 Vue 3 components + composables for the SuperAdmin UI shell. Provides the
 boot loader, manifest loader (ETag cache), nav builder, action registry,
 standard pages (Dashboard, Tenants, Plans, Discovery, …) and the tenant
 self-service building blocks (`FeatureGate`, `useTenantManifest`,
 `PlanChangeWizard`).
 
-Peer dependencies: `vue` (required); `vue-router`, `pinia`, `quasar`
-(optional — see the layers below for what actually needs them).
+Peer dependencies: `vue` (required); `vue-router` and `pinia` (optional — see
+the layers below for what actually needs them). **Not `quasar`**: the components
+are built and carry it as a dependency of this package, so you install
+`@saasicat/ui-vue` and nothing else — no `@quasar/vite-plugin`, no Sass
+([ADR 0011](../../docs/explanation/adr/0011-admin-ui-bundles-quasar.md)).
 
-## Layers
+Three stylesheet imports, once, in your entry:
 
-The package is layered so that each entry only loads what it names.
-Lower layers never import upward; ESLint (`no-restricted-imports`, repo
-root config) enforces the boundaries in CI.
+```ts
+import '@saasicat/ui-vue/quasar.css'; // the framework's own reset
+import '@saasicat/ui-vue/icons.css'; // the icon font the components render
+import '@saasicat/ui-vue/theme.css'; // the design tokens
+import '@saasicat/ui-vue/style.css'; // the components' own styles
+```
 
-| Entry                                                                                           | Source                           | May import                               | Contents                                                                                                                                                                                                                                                         |
-| ----------------------------------------------------------------------------------------------- | -------------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `@saasicat/ui-vue/client`                                                                       | `src/client/`                    | `@saasicat/core` only                    | Framework-free core: `BootLoader`, `ManifestLoader` (ETag cache), nav builder, action registry, batch column fetcher, the `HttpClient`/`KvStore` contract with its `fetch` and axios adapters, `AdminError`. Usable from any framework or plain Node/TypeScript. |
-| `@saasicat/ui-vue` (main)                                                                       | `src/vue/` (+ client re-exports) | Vue, `vue-router`, Pinia — **no Quasar** | Composables (`useTenants`, `usePlanEditor`, …), router guards, injection keys + shell contract, notify-port type, optional Pinia store factory.                                                                                                                  |
-| `@saasicat/ui-vue/quasar`                                                                       | `src/quasar/`                    | everything above + Quasar                | `createSuperAdminApp()` bootstrap and the Quasar notify-port implementation.                                                                                                                                                                                     |
-| `@saasicat/ui-vue/pages/*.vue`, `/layouts/*.vue`, `/auth/*.vue`, `/ui/*.vue`, `/pages-tenant/*` | SFC directories                  | everything                               | The Quasar reference UI, shipped as raw `.vue` from `src/` (compiled by the consumer's Vite).                                                                                                                                                                    |
+Quasar's stylesheet restyles `html`, `body` and typography — 76 computed
+properties across every element of a page that styles itself. That is why it is
+an import you write rather than one the package hides inside its bundle.
+
+## What this is not
+
+Not a component library to pick from. It is the SuperAdmin application's
+inside: complete pages, the shell around them, the theme they read and the
+data layer beneath them. Taking one primitive out of context is possible and
+rarely what you want.
+
+Not a design system for your product, either. The `Admin*` roster exists for
+admin surfaces; everything else is Quasar, styled through the theme.
+
+Compiled, since 1.0: your bundler loads `dist/`. Your **type**checker still
+reads the `.vue` sources through the `types` condition, which is why that source
+stays within ES2021 and why the floor below still applies.
+
+## Entry points
+
+The package is layered so that each entry only loads what it names. Lower
+layers never import upward, and ESLint enforces it — the reasoning is in
+[ADR 0004](../../docs/explanation/adr/0004-ui-vue-layer-boundaries.md).
+
+| Entry                 | Source          | May import                    | When you take it                                                                                                                                                                     |
+| --------------------- | --------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `./client`            | `src/client/`   | `@saasicat/core` only         | Framework-free: loaders, nav builder, action registry, the resource descriptors, `HttpClient`/`KvStore` with their `fetch` and axios adapters, `AdminError`. Usable from plain Node. |
+| `.`                   | `src/vue/`      | Vue, `vue-router`, Pinia      | Composables, router guards, injection keys, `createAdminRoutes`, the store factory. No Quasar.                                                                                       |
+| `./quasar`            | `src/quasar/`   | everything above, plus Quasar | `createSuperAdminApp()` and the Quasar implementations of the notify and confirm ports.                                                                                              |
+| `./pages`             | `src/pages/`    | everything                    | `standardAdminChildren()` — the platform's own screens as route children.                                                                                                            |
+| `./pages/*.vue`       | `src/pages/`    | everything                    | One standard page, when you mount it yourself.                                                                                                                                       |
+| `./layouts/*.vue`     | `src/layouts/`  | everything                    | `AdminLayout` — the shell around the pages.                                                                                                                                          |
+| `./auth/*.vue`        | `src/auth/`     | everything                    | The login screen and the first-run setup wizard.                                                                                                                                     |
+| `./ui/*.vue`          | `src/ui/`       | everything                    | The `Admin*` primitives, when you build a page of your own.                                                                                                                          |
+| `./theme.css`         | `src/ui/theme/` | —                             | The design tokens. Import it once; without it the pages render unstyled.                                                                                                             |
+| `./style.css`         | built           | —                             | The components' own styles, extracted into one file. Import it once, beside the theme.                                                                                               |
+| `./quasar.css`        | built           | —                             | Quasar's stylesheet, shipped so you do not install Quasar to get it. It restyles `html`, `body` and typography — which is why it stays an import you write rather than one we hide.  |
+| `./icons.css`         | built           | —                             | The Material icon font the components render through `q-icon`. Without it every icon renders as its ligature name.                                                                   |
+| `./theme/*`           | `src/ui/theme/` | —                             | The individual token layers, for a consumer that overrides roles.                                                                                                                    |
+| `./theme/breakpoints` | `src/ui/theme/` | —                             | The five breakpoint values, for a build that needs them in JavaScript.                                                                                                               |
+| `./vue`               | `src/vue/`      | Vue, `vue-router`, Pinia      | The Vue layer alone, without the client re-exports.                                                                                                                                  |
+| `./testing/*`         | `src/testing/`  | everything                    | Fixtures for component and end-to-end tests against the pages.                                                                                                                       |
+
+The four component subpaths keep their `.vue` specifier and resolve two ways:
+your **type**checker reads the source, your **bundler** loads the build. That
+split is what removed Quasar from your `package.json` without changing a single
+import of yours —
+[ADR 0011](../../docs/explanation/adr/0011-admin-ui-bundles-quasar.md). The
+source is still yours to compile for types, so the floor below still holds
+([ADR 0005](../../docs/explanation/adr/0005-ship-sfc-source-not-dist.md)).
 
 ### The shipped source has a language floor
 
@@ -34,7 +86,8 @@ minimum compiler. The language level is checked rather than promised:
 `pnpm --filter @saasicat/ui-vue test:shipped-source` compiles the closure
 reachable from every source-shipping subpath at that level, with
 `isolatedModules`, `useDefineForClassFields` and `strictPropertyInitialization`
-set the way a Vite app sets them, and CI runs it. The directories come from the export map, so a new source subpath
+set the way a Vite app sets them, and CI runs it. The directories come from the export map, so a new
+source subpath
 is covered the day it is added. The compiler version is not checked — `satisfies`
 in the shipped source needs 4.9 or newer whatever `lib` says, and testing that
 would mean installing old compilers.
@@ -121,11 +174,13 @@ mount('#app');
 The fastest way to a running admin app is the scaffolder:
 
 ```bash
-pnpm create saasicat-admin admin --project-key=myapp
+pnpm create saasicat-admin admin --app-key=myapp
 ```
 
-See the [quickstart](https://github.com/uelker70/saasicat/blob/main/docs/quickstart.md) (step 9) for the full setup
-and the [handbook](https://github.com/uelker70/saasicat/blob/main/docs/handbook.md) for the architecture.
+See the [quickstart](https://github.com/uelker70/saasicat/blob/main/docs/quickstart.md) (step 9) for
+the full setup
+and the [architecture](https://github.com/uelker70/saasicat/blob/main/docs/explanation/architecture.md)
+for how the pieces fit.
 
 ## Language
 
@@ -145,7 +200,7 @@ own call: `i18n.locales` narrows the set, `i18n.additionalLocales` adds
 languages the platform does not ship, `i18n.overrides` replaces individual
 strings, and `i18n.switcher: false` drops the control entirely. Components read
 the catalog via `useSaMessages('<namespace>')` / `useSuperAdminI18n()`.
-See [handbook §8.7](https://github.com/uelker70/saasicat/blob/main/docs/handbook.md#87-ui-language-i18n).
+See [UI language](https://github.com/uelker70/saasicat/blob/main/docs/guides/build-the-admin-frontend.md#ui-language-i18n).
 
 ## Build
 
@@ -153,5 +208,15 @@ See [handbook §8.7](https://github.com/uelker70/saasicat/blob/main/docs/handboo
 pnpm --filter @saasicat/ui-vue build
 ```
 
-Produces `dist/{index,client/index,quasar/index}.{js,cjs,d.ts}` via tsup
-(`tsup.config.ts`); `vue`, `vue-router`, `pinia` and `quasar` stay external.
+Two builders. tsup (`tsup.config.ts`) produces
+`dist/{index,client/index,vue/index,quasar/index}.{js,cjs,d.ts}`; Vite
+(`vite.build.config.ts`) compiles the components, one entry each, and copies
+Quasar's stylesheet and the icon font beside them. `vue`, `vue-router` and
+`pinia` stay external in both; `quasar` is external too and travels as a
+dependency of this package.
+
+## Next
+
+- [Build the admin frontend](../../docs/guides/build-the-admin-frontend.md) — wiring it into an app
+- [Design guide](../../docs/explanation/design-guide.md) — the page recipe and the colour roles
+- [Pages take resources, not callbacks](../../docs/explanation/adr/0008-resource-ports-over-props.md)

package/dist/.build-stamp

@@ -1 +1 @@
-14b1904cc8763759de50625a5589d989cdf7e6be7f84abe3f6c54aa3ca8ac9ae
+e8f376ec180b1cf9e82413687a0ad2d83b23d267dbc7682b960e94e42fb0beaf

package/dist/assets/material-icons/material-icons.css

@@ -0,0 +1,31 @@
+@font-face {
+  font-family: 'Material Icons';
+  font-style: normal;
+  font-weight: 400;
+  font-display: block;
+  src: url('./web-font/flUhRq6tzZclQEJ-Vdg-IuiaDsNcIhQ8tQ.woff2') format('woff2'), url('./web-font/flUhRq6tzZclQEJ-Vdg-IuiaDsNa.woff') format('woff');
+}
+
+.material-icons {
+  font-family: 'Material Icons';
+  font-weight: normal;
+  font-style: normal;
+  display: inline-block;
+  line-height: 1;
+  text-transform: none;
+  letter-spacing: normal;
+  word-wrap: normal;
+  white-space: nowrap;
+  direction: ltr;
+
+  /* Support for all WebKit browsers. */
+  -webkit-font-smoothing: antialiased;
+  /* Support for Safari and Chrome. */
+  text-rendering: optimizeLegibility;
+
+  /* Support for Firefox. */
+  -moz-osx-font-smoothing: grayscale;
+
+  /* Support for IE. */
+  font-feature-settings: 'liga';
+}