classcard-ui 0.2.1523 → 0.2.1524-beta.0

package/README.md

@@ -22,3 +22,119 @@ npm run lint
 
 ### Customize configuration
 See [Configuration Reference](https://cli.vuejs.org/config/).
+
+---
+
+## Consuming `classcard-ui`
+
+The package ships **two** builds from one npm package. Nothing about the classic
+global install changed — the tree-shakeable build is purely additive.
+
+### Build outputs
+
+| Field | File | Used by |
+| --- | --- | --- |
+| `main` | `dist/classcard-ui.umd.min.js` | `require()` / `Vue.use()` consumers (unchanged) |
+| `module` | `dist/esm/index.js` | Bundlers (webpack/nuxt/vite) — tree-shakeable |
+| `exports["./components/*"]` | `dist/esm/components/*/index.js` | Per-component deep imports |
+
+Build both with:
+
+```bash
+npm run build-lib      # = clean-dist + build-bundle (UMD) + build-esm (Rollup)
+```
+
+(`npm run build-bundle` builds only the UMD monolith; `npm run build-esm` builds
+only the tree-shakeable `dist/esm`. The publish scripts run `build-lib`.)
+
+### Option A — global install (existing, unchanged)
+
+Registers **all** ~64 components globally. Every page loads the full ~1.9 MB UMD
+bundle. Keep using this if you don't want to touch your build config.
+
+```js
+import classcardUI from "classcard-ui";
+import "classcard-ui/dist/classcard-ui.css";
+
+Vue.use(classcardUI); // registers <c-button>, <c-table>, … everywhere
+```
+
+### Option B — named imports (tree-shakeable)
+
+Import only what you use. Your bundler drops every component you don't reference,
+**and the heavy dependency of each unused component** (quill, filestack-js,
+v-calendar, vue-good-table, vue-tel-input, @shopify/draggable, …). Those libs are
+marked `external` in the ESM build, so they are only pulled in for the components
+that actually import them.
+
+```js
+import { CButton, CInput } from "classcard-ui";
+import "classcard-ui/dist/classcard-ui.css"; // still needed — see "Styles" below
+
+export default {
+  components: { CButton, CInput }, // quill/filestack/v-calendar NOT bundled
+};
+```
+
+### Option C — "slim mode": keep every `<c-*>` tag, drop `Vue.use`
+
+This is the zero-usage-change upgrade path. Remove `Vue.use(classcardUI)` and add
+the bundled resolver for [`unplugin-vue-components`](https://github.com/unplugin/unplugin-vue-components).
+Every existing `<c-button>` / `<c-table>` template tag then **auto-imports** its own
+per-component ESM module — so you get tree-shaking with **no changes to any template**.
+
+**webpack:**
+
+```js
+// webpack.config.js
+const Components = require("unplugin-vue-components/webpack");
+const ClasscardUIResolver = require("classcard-ui/resolver");
+
+module.exports = {
+  plugins: [
+    Components.default({
+      resolvers: [ClasscardUIResolver()],
+    }),
+  ],
+};
+```
+
+**Nuxt 2 (`buildModules`):**
+
+```js
+// nuxt.config.js
+import Components from "unplugin-vue-components/webpack";
+import ClasscardUIResolver from "classcard-ui/resolver";
+
+export default {
+  build: {
+    plugins: [Components({ resolvers: [ClasscardUIResolver()] })],
+  },
+};
+```
+
+Then delete `Vue.use(classcardUI)` and keep the CSS import. No `<c-*>` tag changes.
+
+### Styles
+
+CSS is still one shared file (`dist/classcard-ui.css`, ~75 KB) — Tailwind utility
+classes live there and are **not** in the per-component JS. Import it once,
+globally, in every mode above:
+
+```js
+import "classcard-ui/dist/classcard-ui.css";
+```
+
+(Per-SFC `<style scoped>` rules are injected by the ESM modules themselves, so
+scoped styles work in slim mode even before the global CSS loads. Per-component
+CSS splitting of the shared file is a possible future improvement.)
+
+### Notes
+
+- `vue` is a **peer dependency** (`^2.6.14`) — provided by the host app.
+- The heavy libs are regular `dependencies`, so `npm i classcard-ui` installs
+  them, but Options B/C only *bundle* the ones you actually use.
+- `Vue.use(classcardUI)` also registers the `FocusTrap` component and the
+  `v-scroll-lock` directive globally. In slim mode, components that rely on the
+  `v-scroll-lock` directive need it registered by the host app
+  (`Vue.use(require("v-scroll-lock").default)`).