@jtakeit/kit 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,175 @@
-# Temporary Holding Version
+# @jtakeit/kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The half of a site on [jtakeit](https://jtakeit.com) that does not depend on
+how the site is built.
+
+[`@jtakeit/astro`](https://www.npmjs.com/package/@jtakeit/astro) is the
+scaffold the platform ships: an Astro project with the contract already on
+it. Everything in it that is not Astro's lives here, so a site on any other
+static generator — Eleventy, a Next export, Nuxt, SvelteKit, a Node script —
+takes the same pieces instead of reproducing them. The scaffold itself
+imports this package; there is one implementation of each piece and two
+homes for it.
+
+What the platform holds a repository to is in
+[connecting a site](https://jtakeit.com/docs/guides/connecting-a-site), under
+*On another generator*. This package is the pieces of that list that are
+worth not writing twice.
+
+## The booking form
+
+The platform's diary, on the page: the free times fetched, a stay of several
+nights, a class of cars, a party, the words in the business's kind, the
+payment step, Turnstile when the host has it. The contract it keeps is
+[bookings on the site](https://jtakeit.com/docs/guides/bookings-on-the-site);
+`preflight` reads `data-sends` off the built page and books in exactly that
+shape, so the form says what it sends and the element sends nothing else.
+
+**At build time**, the markup:
+
+```js
+import { renderBookingForm } from '@jtakeit/kit/booking';
+
+const html = renderBookingForm({
+  services,                 // [{ slug, title, takes, costs, group }], the entries with `takes`
+  resources,                // [{ slug, title }] — leave empty for a solo business
+  locale: 'uk',             // uk, de or en: the words before the platform has spoken
+  combine: settings.combine === true,   // jtk/bookings.json
+  scale: settings.scale ?? '',          // 'daily' for a business that lets by the day
+  kind: settings.kind ?? '',            // whose words to wait for
+  currency: site.business.currency,
+  api: `${base}api/`,       // where /api/ is from this page — under the preview the site is served at /p/<slug>/
+});
+```
+
+Put the string on the page where the site sends people to book — the one
+`page` in `jtk/bookings.json` names. In Eleventy that is a shortcode; in a
+Next export `dangerouslySetInnerHTML`; in a script, a template literal.
+
+**On the page**, the behaviour, once:
+
+```html
+<script type="module">import '@jtakeit/kit/elements/booking';</script>
+```
+
+The markup comes wrapped in `<jtk-booking>`, and the element wires the form
+when it reaches the document — on load, and when the panel places it later.
+A form written by hand is wired too, as long as it keeps the `data-*` hooks
+and the input `name`s of the rendered one: `wireAll()` walks the document at
+load and again on the panel's `fl:placed`.
+
+**The look** is the site's to give. `@jtakeit/kit/booking.css` makes the form
+legible and nothing more; `field`, `field__input`, `booking__slot`,
+`booking__submit` are names to restyle with the site's own fields and
+buttons. Keep the `[hidden]` rule.
+
+Under `base` — a site served from a path, which every preview is — pass
+`api` as your generator writes a root-relative address, so the form posts to
+`/p/<slug>/api/book` on the preview and to `/api/book` on the site's own host.
+
+## The enquiry form
+
+`/api/lead`, which the platform serves beside every site. The form is a real
+`<form method="post">` first — with scripts off the browser posts it and the
+platform answers with a page — and the element only spares a working browser
+the navigation. What the build's lint holds it to: a `name` control, one of
+`contact`, `phone` or `email`, the honeypot `website`, and nothing else that
+the collecting block does not declare in `asks`
+([the contract](https://jtakeit.com/docs/reference/contract.md)).
+
+```js
+import { renderLeadForm } from '@jtakeit/kit/lead';
+
+const html = renderLeadForm({
+  action: `${base}api/lead`,      // under the preview the site is served at /p/<slug>/
+  copy: { title, lead, name, contact, message, requiredNote, submit, sending, success, error, invalidName, invalidContact },
+  asks: [{ key: 'topic', label: 'What it is about', kind: 'text', max: 120 }],   // the block's `asks`, labels resolved
+  paths: { title: 'blocks[3].title', lead: 'blocks[3].lead', name_label: 'blocks[3].name_label', /* … */ },  // the block's fields' data-jtk-path, when annotating
+});
+```
+
+```html
+<script type="module">import '@jtakeit/kit/elements/lead';</script>
+```
+
+`copy` is the collecting block's own words — the owner edits them by tapping,
+which is what `paths` annotates — and `asks` are the catalogue's, drawn fixed.
+`@jtakeit/kit/lead.css` is the legible minimum; keep `.trap` off-screen
+whatever you restyle.
+
+## `_meta.json`, and the specimen pages
+
+What the edge needs to know that the HTML cannot say: the redirects, the
+unfinished entries (built, and served only to an editing session), and the
+directory whose file names carry a content hash, which the edge caches for a
+year. The scaffold writes it from an Astro hook; any build step can:
+
+```js
+import { writeMeta } from '@jtakeit/kit/meta';
+
+await writeMeta('dist', {
+  collections, blocks, locales,      // the declaration: the specimens are derived from it
+  immutable: ['/_next/static/'],     // where this generator keeps its hashed files; absent, the edge assumes Astro's
+  redirects: [{ from: '/old', to: '/new', status: 301 }],
+});
+```
+
+The **specimen pages** are the one thing in that list a site has to build as
+well as declare: one page per block a post may hold, at
+`<collection prefix>/_fl-<type>[-<view>]/` and per extra language — the panel
+lifts the markup for a block the owner has just put into a post from there,
+in the site's own stylesheet. `specimenAddresses(collections, blocks,
+locales)` is the rule; build a page at each address that renders the block
+once, and `writeMeta` lists them as drafts so a stranger never sees one.
+
+A script that attaches to a selector attaches again on the markup the panel
+places — `onAlive(selector, start)` from `@jtakeit/kit/elements/alive` is the
+shape, and it listens for the panel's `fl:placed`.
+
+## A kit, laid out
+
+A business of a kind the platform knows starts from its kit — the
+collections, the rates and the settings, judged on the platform's side:
+
+```
+npx @jtakeit/kit apply --kit car_rental --locale uk      # asked of the platform by its kind
+npx @jtakeit/kit apply --kit ./car_rental.json           # or a file of it
+```
+
+writes `jtk/bookings.json` with `page` at the services' listing and `kit` /
+`kit_version` recorded, the rates as entries under `jtk/content`, and the
+kit's block types, collections and module into `jtk/catalogue.json` (a type
+or a collection the site already has by that name is left alone). The
+scaffold does the same through `jtk create --kit`, writing the declaration
+into `src/content/blocks.ts` instead of the catalogue file. `@jtakeit/kit/kits`
+has the pieces — `loadKit`, `kitSettings`, `kitEntries`,
+`mergeKitIntoCatalogue`, `layKitFiles` — for a tool of your own.
+
+## The catalogue tool
+
+```
+npx @jtakeit/kit catalogue --declaration src/content/blocks.ts --emit-only
+npx @jtakeit/kit catalogue --declaration src/content/blocks.ts --dist ./dist
+npx @jtakeit/kit catalogue … --judge        # and ask the platform's validator whether we agree
+```
+
+Derives `jtk/catalogue.json` from a declaration module — the scaffold's
+`src/content/blocks.ts` shape: `BLOCKS`, `PAGE_SEO`, `BUSINESS_FACTS`,
+`COLLECTIONS`, `MODULES`, `LOCALES` — and checks it against a built `dist/`
+both ways: every declared field rendered with its `data-jtk-path`, every
+annotated path declared. On an Astro project it also builds once more under
+a path to prove every address stays inside the preview; on another generator
+build that way yourself (`SITE_URL=https://x.invalid/p/check/`) and pass
+`--dist`. `@jtakeit/astro catalogue` is this tool, signing the file as the
+scaffold.
+
+## Also here
+
+- `@jtakeit/kit/money` — a price as the page says it: «2 300 ₴», no kopecks
+  on a whole price, no sign where the site has not said its currency.
+- `@jtakeit/kit/booking/words` — the form's words per language, the salon's
+  and the letting business's by the day, before the platform corrects them.
+- `@jtakeit/kit/codes` — the catalogue's error codes, a copy of the platform's
+  table that `--judge` keeps honest.
+
+`@jtakeit/astro` stays the scaffold and is a thin layer over all of this.

package/bin/jtkit.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+/**
+ * jtkit — the command line of @jtakeit/kit, for a site on any generator.
+ *
+ *   jtkit apply --kit <kind>|<file> [--locale uk] [--api <url>] [--root <dir>]
+ *       lay a booking kit out: jtk/bookings.json, the rates as entries, and the
+ *       kit's types, collections and module into jtk/catalogue.json
+ *   jtkit catalogue [--declaration src/content/blocks.ts] [--emit-only] [--dist ./dist] [--judge]
+ *       write jtk/catalogue.json from a declaration and check it against the built pages
+ */
+import { pathToFileURL } from 'node:url';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { relative } from 'node:path';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const [command, ...rest] = process.argv.slice(2);
+const has = (name) => rest.includes(`--${name}`);
+const flag = (name, fallback) => {
+  const at = rest.indexOf(`--${name}`);
+  return at === -1 ? fallback : rest[at + 1];
+};
+
+switch (command) {
+  case 'apply': {
+    const { loadKit, layKitFiles } = await import(pathToFileURL(join(HERE, '..', 'lib', 'kits.mjs')).href);
+    const asked = has('kit') ? flag('kit', '') : has('kind') ? flag('kind', '') : '';
+    if (asked === '') {
+      console.error('jtkit apply: --kit <kind> or --kit <file> says which kit');
+      process.exit(1);
+    }
+    const root = resolve(flag('root', process.cwd()));
+    try {
+      const kit = await loadKit(asked, flag('api', undefined));
+      const written = layKitFiles(root, kit, { locale: flag('locale', 'en'), catalogue: true });
+      console.log(`${written.length} files written under ${relative(process.cwd(), root) || '.'}:`);
+      for (const file of written) console.log(`  ${relative(root, file)}`);
+      console.log(`\nThe «${kit.kind}» kit is laid out. Ask, never make up:`);
+      for (const line of kit.ask ?? []) console.log(`  - ${line}`);
+      console.log(`What the kit chose for the business — say each back and get a yes: jtakeit:///kits/${kit.kind}.md, «Taken by default».`);
+    } catch (why) {
+      console.error(`jtkit apply: ${why.message}`);
+      process.exit(1);
+    }
+    break;
+  }
+  case 'catalogue':
+  case 'catalog': {
+    process.argv = [process.argv[0], process.argv[1], ...rest];
+    await import(pathToFileURL(join(HERE, '..', 'lib', 'catalogue.mjs')).href);
+    break;
+  }
+  default: {
+    console.error(`@jtakeit/kit — the framework-free half of a site on jtakeit
+
+  jtkit apply --kit <kind>|<file> [--locale uk] [--api <url>] [--root <dir>]
+  jtkit catalogue [--declaration src/content/blocks.ts] [--emit-only] [--dist ./dist] [--judge]
+
+The contract the platform holds a repository to: https://jtakeit.com/docs/guides/connecting-a-site`);
+    process.exit(command === undefined || command === '--help' || command === '-h' ? 0 : 1);
+  }
+}

package/booking.css

@@ -0,0 +1,36 @@
+/*
+ * The booking form, legible and nothing more.
+ *
+ * A reference, not a design: `field`, `field__input`, `booking__slot` and
+ * `booking__submit` are names for the site to restyle with its own fields and
+ * buttons, the way the scaffold's booking.md asks. Keep the `data-*` hooks and
+ * the `[hidden]` rule below whatever you do to the rest.
+ */
+.booking { display: grid; gap: var(--space-4, 1rem); max-width: 34rem; }
+
+/* The kind's words, until the platform has said them: the space kept, the
+   salon's word not shown at a car rental. */
+.booking--unsaid [data-say], .booking--unsaid [data-say-wait] { visibility: hidden; }
+
+.booking__times { border: 0; padding: 0; margin: 0; }
+.booking__services { border: 0; padding: 0; margin: 0; display: grid; gap: 0.75rem; }
+.booking__run { display: grid; gap: 0.35rem; }
+.booking__run-title { margin: 0.5rem 0 0.15rem; font-size: 0.75rem; font-weight: 700; letter-spacing: 0.12em; text-transform: uppercase; opacity: 0.7; }
+.booking__service { display: grid; grid-template-columns: auto 1fr auto; gap: 0.6rem; align-items: baseline; padding: 0.45rem 0; border-block-end: 1px solid var(--line, #e5e1d8); cursor: pointer; }
+.booking__service-meta { font-size: 0.85em; opacity: 0.7; white-space: nowrap; }
+.booking__total { margin: 0.25rem 0 0; font-weight: 600; }
+.booking__slots { display: flex; flex-wrap: wrap; gap: 0.4rem; }
+.booking__slot {
+  font: inherit; padding: 0.45rem 0.75rem; border-radius: var(--radius-sm, 0.5rem);
+  border: 1px solid var(--color-line, currentColor); background: transparent; color: inherit; cursor: pointer;
+}
+.booking__slot.is-chosen { background: var(--color-ink, #111); color: var(--color-bg, #fff); border-color: var(--color-ink, #111); }
+.booking__hint, .booking__note { margin: 0; opacity: 0.75; }
+.booking__links { display: flex; flex-wrap: wrap; gap: 0.75rem 1.25rem; margin: 0; }
+.booking__done-line { font-weight: 600; margin: 0; }
+.booking__done-when { margin: 0; }
+
+/* `hidden` means hidden, whatever the element's class says: every state here
+   is shown and hidden by the attribute, and a class that sets `display` would
+   otherwise win (an agent's rehearsal, 30 September 2026). */
+.booking [hidden] { display: none !important; }

package/elements/alive.js

@@ -0,0 +1,52 @@
+/**
+ * Initialising something on the page, in the two places it can arrive.
+ *
+ * ── why there are two ───────────────────────────────────────────────────────
+ *
+ * Everything on a page arrives at load, and a script that queries the document
+ * once and attaches what it needs is correct — until something is put on the
+ * page afterwards. Then it is not: the new node was never seen, its listeners
+ * were never attached, and it sits there inert.
+ *
+ * That happens here for one reason and it is worth knowing. The platform's
+ * panel shows the owner a *preview of this site* while they write, and when
+ * they put a gallery into a post the built page has no element for it. Rather
+ * than drawing its own — it would be guessing at this repository's markup and
+ * CSS — it takes the arrangement from a specimen page this build made and puts
+ * it where the block goes. What arrives is this site's own markup, in this
+ * site's own stylesheet, and everything declarative about it is already right.
+ *
+ * What is not right is anything a script was supposed to do to it. So the
+ * panel fires `fl:placed` on the new node, and this is how a site listens.
+ *
+ * ── the shape it forces, which is the shape you wanted anyway ───────────────
+ *
+ * An initialiser registered here is called with a root and must work on it:
+ * once with the document at load, and again with a subtree when one appears. A
+ * function written that way is also the function that survives view
+ * transitions and anything else that swaps part of a page — the browser's own
+ * answer, `connectedCallback`, has the same shape for the same reason.
+ *
+ * Idempotent by scope rather than by flag: it is never called twice with the
+ * same node, because the node it is called with is the new one.
+ *
+ * @param {string} selector
+ * @param {(node: Element) => void} start
+ */
+export function onAlive(selector, start) {
+  const wake = (root) => {
+    if (root instanceof Element && root.matches(selector)) start(root);
+    for (const node of root.querySelectorAll(selector)) start(node);
+  };
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', () => wake(document), { once: true });
+  } else {
+    wake(document);
+  }
+
+  document.addEventListener('fl:placed', (event) => {
+    const at = event.target;
+    if (at instanceof Element) wake(at);
+  });
+}