@echodial/deck 0.1.0 → 0.1.3

package/README.md

@@ -1,6 +1,10 @@
 # Deck
 
-**Deck is a CSS framework that ships as one 26.7 KB Brotli (32.7 KB gzip) stylesheet: buttons, forms,
+[![npm version](https://img.shields.io/npm/v/@echodial/deck)](https://www.npmjs.com/package/@echodial/deck)
+[![Packagist version](https://img.shields.io/packagist/v/echodial/deck)](https://packagist.org/packages/echodial/deck)
+[![License: MIT](https://img.shields.io/npm/l/@echodial/deck)](LICENSE)
+
+**Deck is a CSS framework that ships as one 26.8 KB Brotli (32.7 KB gzip) stylesheet: buttons, forms,
 tables, a data grid, charts, overlays, an icon sprite, and a full color system. You add it
 with one `<link>` tag. There is no build step, no config file, and zero dependencies.**
 
@@ -19,25 +23,25 @@ That is the whole install. Nothing to compile, nothing to purge, nothing to conf
   whole page with no second stylesheet.
 - **Zero runtime dependencies.** The JavaScript is optional and dependency-free.
 
-Version 0.1.0 · MIT · Chrome 117+, Edge 117+, Safari 17.4+, Firefox 128+
+Version 0.1.3 · MIT · Chrome 117+, Edge 117+, Safari 17.4+, Firefox 128+
 
 ## What Deck weighs
 
-A page that loads the stylesheet, the icon sprite, and the optional JavaScript transfers **62.7 KB** Brotli, or **76.3 KB** gzip. Every browser Deck supports sends `br` in
+A page that loads the stylesheet, the icon sprite, and the optional JavaScript transfers **62.8 KB** Brotli, or **76.3 KB** gzip. Every browser Deck supports sends `br` in
 `Accept-Encoding`, and Cloudflare, Vercel, Netlify, and nginx with `ngx_brotli` negotiate
 it for text by default, so Brotli is what most users actually receive.
 
 | File | Brotli | gzip |
 | --- | --- | --- |
-| `deck.min.css` | **26.7 KB** | 32.7 KB |
+| `deck.min.css` | **26.8 KB** | 32.7 KB |
 | `deck-icons.svg` | **27.1 KB** | 33.6 KB |
 | `deck.min.js` | **8.9 KB** | 10.0 KB |
-| **All three** | **62.7 KB** | **76.3 KB** |
+| **All three** | **62.8 KB** | **76.3 KB** |
 
 The sprite is the largest single file, slightly bigger than the stylesheet — worth stating
 plainly rather than leaving you to find it in devtools. Swapping `deck.min.js` for the full
-`deck.bundle.min.js` (adds the date picker, combobox, data grid, toasts, QR encoder)
-makes the JavaScript 17.3 KB and the total 71.1 KB Brotli (85.8 KB gzip).
+`deck.bundle.min.js` (adds the carousel, drawer, mega menu, copy button, QR encoder, editor and library adapters)
+makes the JavaScript 17.3 KB and the total 71.2 KB Brotli (85.8 KB gzip).
 
 ### The sprite is a manifest, not a fixed cost
 
@@ -70,9 +74,9 @@ brand marks through from the previous sprite, and dropping them drops the marks.
 
 | File | Brotli | gzip | What it is |
 | --- | --- | --- | --- |
-| `deck.min.css` | 26.7 KB | 32.7 KB | The whole framework |
+| `deck.min.css` | 26.8 KB | 32.7 KB | The whole framework |
 | `deck.min.js` | 8.9 KB | 10.0 KB | Optional behaviour, no dependencies |
-| `deck-extras.min.js` | 5.7 KB | 6.5 KB | Date picker, combobox, data grid, toasts, QR encoder |
+| `deck-extras.min.js` | 5.7 KB | 6.5 KB | Carousel, drawer, mega menu, copy button, QR encoder, editor |
 | `deck-adapters.min.js` | 4.0 KB | 4.5 KB | Optional library integrations, inert unless one is loaded |
 | `deck.bundle.min.js` | 17.3 KB | 19.5 KB | All three scripts in one file |
 | `deck-icons.svg` | 27.1 KB | 33.6 KB | 152 symbols: 75 icons at two weights, plus two brand marks |
@@ -150,18 +154,21 @@ npm start         # php -S localhost:4321 -t public_html
 
 ## Install
 
-Deck ships three ways. Pick whichever matches how the project already works.
+Deck is published to npm as `@echodial/deck` and to Packagist as `echodial/deck`, and the
+CDNs mirror npm. That makes four ways to install it; pick whichever matches how the
+project already works.
 
 ### 1. Just the files
 
-Download `deck.css` and `deck-icons.svg`, drop them next to your other assets, and add
-one line. No package manager, no build step, no Node on the server.
+Put `deck.css` and `deck-icons.svg` next to your other assets and add one line. No
+package manager in the project, no build step, no Node on the server.
 
 ```html
-<link rel="stylesheet" href="/assets/deck.css">
+<link rel="stylesheet" href="/assets/deck/deck.css">
 ```
 
-Or let the CLI put them there for you — this does not install anything permanently:
+The CLI copies them for you. It runs straight from npm and adds nothing to your
+dependencies:
 
 ```bash
 npx @echodial/deck init public/assets/deck
@@ -176,9 +183,12 @@ npm install @echodial/deck
 
 ```js
 import '@echodial/deck/css';
-import Deck from '@echodial/deck';
+import '@echodial/deck/bundle';   // sets window.Deck
 ```
 
+In 0.1.2, `import Deck from '@echodial/deck'` does not build: the file it resolves to ends in
+an export that is not valid JavaScript. Import the bundle for its side effect instead.
+
 Subpath exports, so you can take only what you need:
 
 | Import | What it is |
@@ -186,8 +196,8 @@ Subpath exports, so you can take only what you need:
 | `@echodial/deck/css` | the whole stylesheet |
 | `@echodial/deck/css/min` | minified |
 | `@echodial/deck/icons` | the sprite |
-| `@echodial/deck/js` | core behaviour |
-| `@echodial/deck/extras` | datepicker, combobox, grid, toasts, QR |
+| `@echodial/deck/js` | core behaviour: toasts, theme switch, date picker, combobox, data grid |
+| `@echodial/deck/extras` | carousel, drawer, mega menu, copy button, QR, editor |
 | `@echodial/deck/adapters` | optional library integrations |
 | `@echodial/deck/bundle` | all three in one file |
 | `@echodial/deck/layers/tokens.css` | one layer at a time |
@@ -199,11 +209,24 @@ reasonable way to adopt it into an existing app one screen at a time.
 
 ### 3. CDN
 
-Publishing to npm makes the CDNs work with no extra step:
+jsDelivr and unpkg mirror every version published to npm:
 
 ```html
 <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@echodial/deck@0.1/dist/deck.min.css">
-<script src="https://cdn.jsdelivr.net/npm/@echodial/deck@0.1/dist/deck.bundle.min.js" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/@echodial/deck@0.1/dist/deck.bundle.min.js" data-deck-icons="/assets/deck/deck-icons.svg" defer></script>
+```
+
+Pin the version to `@0.1`, as above. It follows every 0.1.x release and never moves to 0.2.
+Never use `@latest`, or leave the version off, which means the same thing: either one moves
+your page onto the next breaking release the day it is published, with nothing in your code
+to show why.
+
+The icon sprite is the one file a CDN cannot serve. Browsers refuse an SVG `<use>` whose
+`href` is on another origin, so serve `deck-icons.svg` from your own site and point
+`data-deck-icons` at it:
+
+```bash
+curl -sSL --create-dirs -o public/assets/deck/deck-icons.svg https://cdn.jsdelivr.net/npm/@echodial/deck@0.1/dist/deck-icons.svg
 ```
 
 ### 4. Composer
@@ -212,11 +235,21 @@ Publishing to npm makes the CDNs work with no extra step:
 composer require echodial/deck
 ```
 
-Assets cannot be served out of `vendor/`, so the package publishes them into your public
-directory on install. Configure the destination in your own `composer.json`:
+On its own, that installs Deck into `vendor/` and nothing else. A browser cannot read
+`vendor/`, and Composer never runs scripts from a package you install, only the ones in
+your own `composer.json`, so no assets are copied and `composer deck-publish` is not a
+command yet (`Command "deck-publish" is not defined.`). Get the files into your public
+folder one of three ways.
+
+**Opt-in scripts.** Add these to your own `composer.json`, then run `composer require`:
 
 ```json
 {
+  "scripts": {
+    "post-install-cmd": ["EchoDial\\Deck\\Installer::postInstall"],
+    "post-update-cmd": ["EchoDial\\Deck\\Installer::postInstall"],
+    "deck-publish": "EchoDial\\Deck\\Installer::publish"
+  },
   "extra": {
     "deck": {
       "publish-to": "public/assets/deck",
@@ -226,16 +259,40 @@ directory on install. Configure the destination in your own `composer.json`:
 }
 ```
 
-Or run it whenever you like:
+`composer require`, and every `composer install` and `composer update` after it, copies the
+eight asset files into `publish-to`, skipping any that have not changed. If Deck is already
+installed when you add the scripts, run `composer deck-publish` once;
+`composer deck-publish -- public/static/deck` publishes somewhere else for one run. With
+`auto-publish` left out or `false`, the install and update hooks print a reminder instead
+of copying. Take the scripts out if you remove Deck: without the class to call, every
+install prints `Class EchoDial\Deck\Installer is not autoloadable, can not call
+post-install-cmd script`.
+
+> **Set `publish-to` to the folder your web server serves.** The default,
+> `public/assets/deck`, is right for Laravel and Symfony, whose document root is `public/`.
+> On cPanel hosting and Helm sites the document root is `public_html/`, so use
+> `public_html/assets/deck`. Deck cannot tell which folder is served; if `publish-to` names
+> the wrong one, the files land where no URL reaches.
+
+**Copy by hand**, with no scripts at all:
 
 ```bash
-composer deck-publish
-composer deck-publish -- public/static/deck
-composer deck-publish -- --link          # symlink during development
+mkdir -p public/assets/deck
+cp -r vendor/echodial/deck/dist/* public/assets/deck/
 ```
 
-Publishing skips files that have not changed, so a redeploy does not churn mtimes and
-invalidate every cache-busting URL for nothing.
+That copies everything in `dist/`: 50 files and 3.2 MB, where a page needs four of them.
+`api.json` alone is 1.4 MB of build data that no browser requests. Run it again after every
+`composer update`.
+
+**npx**, if Node is on the machine: `npx @echodial/deck init public/assets/deck`, as in
+[option 1](#1-just-the-files), copies the five files a page uses. It takes them from npm,
+not from `vendor/`, so make sure the two are the same version.
+
+Deck's own `composer.json` defines no scripts. Scripts in a dependency never run for the
+project that installs it; the ones Deck used to define could only fire inside Deck's own
+repository, and did, publishing a copy of Deck into itself. The installer also refuses to
+publish whenever the root package is `echodial/deck`.
 
 #### The PHP helper
 
@@ -1203,11 +1260,15 @@ that job over while keeping its own markup, classes, and styling.
 <script src="/assets/deck-extras.js" defer></script>
 <script src="/assets/deck-adapters.js" defer></script>
 
-<!-- add only what you want -->
-<script src="https://cdn.jsdelivr.net/npm/@floating-ui/dom" defer></script>
-<script src="https://cdn.jsdelivr.net/npm/sortablejs" defer></script>
+<!-- add only what you want, each pinned to its major version -->
+<script src="https://cdn.jsdelivr.net/npm/@floating-ui/core@1" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/@floating-ui/dom@1" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/sortablejs@1" defer></script>
 ```
 
+Floating UI's DOM build expects its core to be loaded first. Without it, `FloatingUIDOM`
+exists but has no `computePosition`, and the script throws.
+
 | Job | Deck alone | With a library | Verdict |
 |---|---|---|---|
 | Placement | CSS anchor positioning | Floating UI (~9 KB) | Library only where anchor positioning is missing |

package/build.mjs

@@ -27,6 +27,17 @@ const DIST = path.join(root, 'dist');
 
 const pkg = JSON.parse(await readFile(path.join(root, 'package.json'), 'utf8'));
 
+// php/Deck.php carries the version as a constant, for PHP that has no business
+// parsing package.json, and `composer deck-publish` prints it. A release with
+// the two out of step would announce the wrong version, so refuse to build.
+// php/ is not shipped to npm, so an install without it skips the check.
+const deckPhp = await readFile(path.join(root, 'php', 'Deck.php'), 'utf8').catch(() => null);
+const phpVersion = deckPhp && /const VERSION = '([^']+)'/.exec(deckPhp)?.[1];
+if (deckPhp && phpVersion !== pkg.version) {
+  console.error(`  php/Deck.php has VERSION = '${phpVersion}' but package.json is ${pkg.version}. Make them match.`);
+  process.exit(1);
+}
+
 const BANNER = `/*! ==========================================================================
  *  Deck v${pkg.version} — the CSS framework for Keel
  *  Mobile first. One file. No build step. No config. No dependencies.
@@ -276,7 +287,7 @@ async function build() {
     `/* Deck v${pkg.version} — ES module entry.\n` +
     `   The scripts attach Deck to globalThis; this re-exports it so that\n` +
     `   \`import Deck from '@echodial/deck'\` behaves the way you expect. */\n` +
-    bundle + '\nexport default globalThis.Deck;\nexport { globalThis as __deckGlobal };\n');
+    bundle + '\nexport default globalThis.Deck;\n');
 
   // ---- Sizes ---------------------------------------------------------------
   // One place for every published figure. dist/sizes.json is the single source
@@ -332,6 +343,24 @@ async function build() {
     if (err.code !== 'ERR_MODULE_NOT_FOUND') throw err;
   }
 
+  // ---- Site files -------------------------------------------------------------
+  // sitemap.xml, robots.txt and llms.txt are served as they are, so they cannot
+  // ask PHP for the base URL the pages print. tools/site.mjs writes it into them
+  // from the same inputs, and generates the sitemap from the pages on disk.
+  try {
+    const { writeSiteFiles } = await import('./tools/site.mjs');
+    const site = await writeSiteFiles(pkg, root);
+    console.log(`  ${'sitemap.xml'.padEnd(22)} ${String(site.pages).padStart(6)} pages   ${site.base}/  (${site.source})`);
+    console.log(`  ${'robots.txt'.padEnd(22)} ${String(site.groups).padStart(6)} groups, one rule set, Sitemap line written`);
+    console.log(`  ${'llms.txt'.padEnd(22)} ${String(site.links).padStart(6)} site links written`);
+    if (site.source === 'DECK_SITE_BASE') {
+      console.log(`  ${''.padEnd(22)} DECK_SITE_BASE is set: these three files now name ${site.base}, not package.json's homepage`);
+    }
+  } catch (err) {
+    // tools/ and public_html/ are not shipped to npm.
+    if (err.code !== 'ERR_MODULE_NOT_FOUND') throw err;
+  }
+
   console.log('\nDone.\n');
 }
 

package/dist/api-buckets.json

@@ -965,7 +965,7 @@
       "layer": "deck.components",
       "file": "07-components.css",
       "line": 431,
-      "uses": 12
+      "uses": 14
     },
     "accordion-body": {
       "bucket": "public",
@@ -975,7 +975,7 @@
       "layer": "deck.components",
       "file": "07-components.css",
       "line": 460,
-      "uses": 23
+      "uses": 25
     },
     "actions-cq": {
       "bucket": "public",
@@ -1005,7 +1005,7 @@
       "layer": "deck.components",
       "file": "07-components.css",
       "line": 146,
-      "uses": 56
+      "uses": 60
     },
     "alert-bad": {
       "bucket": "public",
@@ -1015,7 +1015,7 @@
       "layer": "deck.components",
       "file": "07-components.css",
       "line": 169,
-      "uses": 10
+      "uses": 12
     },
     "alert-body": {
       "bucket": "public",
@@ -1025,7 +1025,7 @@
       "layer": "deck.components",
       "file": "07-components.css",
       "line": 160,
-      "uses": 45
+      "uses": 49
     },
     "alert-good": {
       "bucket": "public",
@@ -1045,7 +1045,7 @@
       "layer": "deck.components",
       "file": "07-components.css",
       "line": 163,
-      "uses": 16
+      "uses": 18
     },
     "alert-title": {
       "bucket": "public",
@@ -1055,7 +1055,7 @@
       "layer": "deck.components",
       "file": "07-components.css",
       "line": 157,
-      "uses": 45
+      "uses": 49
     },
     "alert-warn": {
       "bucket": "public",
@@ -1185,7 +1185,7 @@
       "layer": "deck.components",
       "file": "07-components.css",
       "line": 81,
-      "uses": 204
+      "uses": 196
     },
     "badge-bad": {
       "bucket": "public",
@@ -1225,7 +1225,7 @@
       "layer": "deck.components",
       "file": "07-components.css",
       "line": 98,
-      "uses": 48
+      "uses": 46
     },
     "badge-solid": {
       "bucket": "public",
@@ -1245,7 +1245,7 @@
       "layer": "deck.components",
       "file": "07-components.css",
       "line": 100,
-      "uses": 28
+      "uses": 22
     },
     "banner": {
       "bucket": "public",
@@ -1485,7 +1485,7 @@
       "layer": "deck.components",
       "file": "05-buttons.css",
       "line": 7,
-      "uses": 564
+      "uses": 568
     },
     "btn-3d": {
       "bucket": "public",
@@ -1595,7 +1595,7 @@
       "layer": "deck.components",
       "file": "05-buttons.css",
       "line": 72,
-      "uses": 121
+      "uses": 123
     },
     "btn-round": {
       "bucket": "public",
@@ -2275,7 +2275,7 @@
       "layer": "deck.components",
       "file": "06-forms.css",
       "line": 175,
-      "uses": 128
+      "uses": 129
     },
     "check-card": {
       "bucket": "public",
@@ -2355,7 +2355,7 @@
       "layer": "deck.layout",
       "file": "04-layout.css",
       "line": 74,
-      "uses": 367
+      "uses": 369
     },
     "cluster-between": {
       "bucket": "public",
@@ -2635,7 +2635,7 @@
       "layer": "deck.layout",
       "file": "04-layout.css",
       "line": 11,
-      "uses": 99
+      "uses": 101
     },
     "container-full": {
       "bucket": "public",
@@ -3795,7 +3795,7 @@
       "layer": "deck.mobile",
       "file": "08-mobile.css",
       "line": 183,
-      "uses": 60
+      "uses": 61
     },
     "emoji-grid": {
       "bucket": "public",
@@ -4995,7 +4995,7 @@
       "layer": "deck.mobile",
       "file": "08-mobile.css",
       "line": 134,
-      "uses": 616
+      "uses": 627
     },
     "icon-fill": {
       "bucket": "public",
@@ -5005,7 +5005,7 @@
       "layer": "deck.mobile",
       "file": "08-mobile.css",
       "line": 156,
-      "uses": 12
+      "uses": 14
     },
     "icon-follow": {
       "bucket": "public",
@@ -5025,7 +5025,7 @@
       "layer": "deck.mobile",
       "file": "08-mobile.css",
       "line": 154,
-      "uses": 85
+      "uses": 89
     },
     "icon-muted": {
       "bucket": "public",
@@ -5975,7 +5975,7 @@
       "layer": "deck.type",
       "file": "03-type.css",
       "line": 29,
-      "uses": 210
+      "uses": 212
     },
     "lg": {
       "bucket": "public",
@@ -7985,7 +7985,7 @@
       "layer": "deck.components",
       "file": "06-forms.css",
       "line": 288,
-      "uses": 50
+      "uses": 59
     },
     "range-pair": {
       "bucket": "public",
@@ -8445,7 +8445,7 @@
       "layer": "deck.layout",
       "file": "04-layout.css",
       "line": 161,
-      "uses": 86
+      "uses": 88
     },
     "segmented": {
       "bucket": "public",
@@ -8895,7 +8895,7 @@
       "layer": "deck.utilities",
       "file": "09-utilities.css",
       "line": 182,
-      "uses": 127
+      "uses": 137
     },
     "stack": {
       "bucket": "public",
@@ -8935,7 +8935,7 @@
       "layer": "deck.layout",
       "file": "04-layout.css",
       "line": 63,
-      "uses": 485
+      "uses": 487
     },
     "stack-3": {
       "bucket": "public",
@@ -8945,7 +8945,7 @@
       "layer": "deck.layout",
       "file": "04-layout.css",
       "line": 65,
-      "uses": 2144
+      "uses": 2150
     },
     "stack-4": {
       "bucket": "public",
@@ -8955,7 +8955,7 @@
       "layer": "deck.layout",
       "file": "04-layout.css",
       "line": 67,
-      "uses": 312
+      "uses": 314
     },
     "stack-6": {
       "bucket": "public",
@@ -8965,7 +8965,7 @@
       "layer": "deck.layout",
       "file": "04-layout.css",
       "line": 69,
-      "uses": 140
+      "uses": 142
     },
     "stack-8": {
       "bucket": "public",
@@ -9245,7 +9245,7 @@
       "layer": "deck.components",
       "file": "07-components.css",
       "line": 241,
-      "uses": 114
+      "uses": 124
     },
     "table-compact": {
       "bucket": "public",
@@ -9265,7 +9265,7 @@
       "layer": "deck.components",
       "file": "07-components.css",
       "line": 274,
-      "uses": 102
+      "uses": 112
     },
     "table-wrap": {
       "bucket": "public",
@@ -9275,7 +9275,7 @@
       "layer": "deck.components",
       "file": "07-components.css",
       "line": 231,
-      "uses": 111
+      "uses": 121
     },
     "tabs": {
       "bucket": "public",
@@ -9605,7 +9605,7 @@
       "layer": "deck.components",
       "file": "13-toasts.css",
       "line": 49,
-      "uses": 36
+      "uses": 38
     },
     "toast-action": {
       "bucket": "internal",

package/dist/deck.css

@@ -1,5 +1,5 @@
 /*! ==========================================================================
- *  Deck v0.1.0 — the CSS framework for Keel
+ *  Deck v0.1.3 — the CSS framework for Keel
  *  Mobile first. One file. No build step. No config. No dependencies.
  *
  *  <link rel="stylesheet" href="/assets/deck.css">
@@ -12,7 +12,7 @@
  *    deck.mobile, deck.motion, deck.effects, deck.utilities, deck.rtl,
  *    deck.print, then app.base, app.components, app.pages, app.overrides
  *
- *  MIT licence. https://get-keel.dev/deck
+ *  MIT licence. https://get-deck.dev
  *  ======================================================================== */
 
 /* ==========================================================================

package/dist/deck.esm.js

@@ -1,4 +1,4 @@
-/* Deck v0.1.0 — ES module entry.
+/* Deck v0.1.3 — ES module entry.
    The scripts attach Deck to globalThis; this re-exports it so that
    `import Deck from '@echodial/deck'` behaves the way you expect. */
 /*! ==========================================================================
@@ -2641,4 +2641,3 @@ if (typeof module !== 'undefined' && module.exports) module.exports = Deck;
    : typeof Deck !== 'undefined' ? Deck : null);
 
 export default globalThis.Deck;
-export { globalThis as __deckGlobal };