npm - @jtakeit/astro - Versions diffs - 0.1.0 - Mend

@jtakeit/astro 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (68) hide show

package/LICENSE +21 -0
package/README.md +59 -0
package/bin/jtk.mjs +41 -0
package/docs/booking.md +164 -0
package/docs/catalogue.md +459 -0
package/docs/collections.md +249 -0
package/docs/css.md +86 -0
package/docs/gallery.md +127 -0
package/docs/hero-motion.md +189 -0
package/docs/kit.md +454 -0
package/docs/languages.md +182 -0
package/docs/lead-form.md +109 -0
package/docs/pages.md +193 -0
package/docs/photos.md +314 -0
package/docs/scaffold.md +75 -0
package/docs/shapes.md +140 -0
package/docs/surface.md +187 -0
package/lib/catalogue.mjs +1678 -0
package/lib/codes.mjs +171 -0
package/lib/create.mjs +282 -0
package/package.json +16 -0
package/template/astro.config.mjs +84 -0
package/template/figures.mjs +122 -0
package/template/gitignore +16 -0
package/template/jtakeit-meta.mjs +112 -0
package/template/jtk/content/index.json +38 -0
package/template/jtk/design.json +24 -0
package/template/markdown.mjs +36 -0
package/template/package-lock.json +5320 -0
package/template/package.json +26 -0
package/template/specimens.mjs +46 -0
package/template/src/components/Blocks.astro +151 -0
package/template/src/components/BookingForm.astro +506 -0
package/template/src/components/Clip.astro +155 -0
package/template/src/components/Hero.astro +66 -0
package/template/src/components/LeadForm.astro +347 -0
package/template/src/components/OpeningHours.astro +69 -0
package/template/src/components/Pile.astro +185 -0
package/template/src/components/Shot.astro +472 -0
package/template/src/components/gallery/Gallery.astro +381 -0
package/template/src/components/gallery/galleries.ts +139 -0
package/template/src/components/motion/HeroField.astro +520 -0
package/template/src/components/motion/fields.ts +430 -0
package/template/src/components/surface/Pattern.astro +278 -0
package/template/src/components/surface/patterns.ts +187 -0
package/template/src/content/blocks.ts +758 -0
package/template/src/content.config.ts +19 -0
package/template/src/copy/LOCALE.ts +324 -0
package/template/src/data/site.ts +137 -0
package/template/src/layouts/Layout.astro +282 -0
package/template/src/lib/alive.ts +49 -0
package/template/src/lib/entries.ts +106 -0
package/template/src/lib/entryLoader.ts +315 -0
package/template/src/lib/noise.ts +26 -0
package/template/src/lib/page.ts +287 -0
package/template/src/lib/photos.ts +168 -0
package/template/src/lib/under.ts +32 -0
package/template/src/lib/uploads.ts +85 -0
package/template/src/pages/[...entry].astro +207 -0
package/template/src/pages/[...feed].xml.ts +64 -0
package/template/src/pages/index.astro +90 -0
package/template/src/pages/llms.txt.ts +50 -0
package/template/src/pages/privacy.astro +59 -0
package/template/src/pages/robots.txt.ts +21 -0
package/template/src/pages/sitemap.xml.ts +50 -0
package/template/src/styles/global.css +411 -0
package/template/src/styles/surface.css +375 -0
package/template/tsconfig.json +5 -0

package/docs/scaffold.md ADDED Viewed

@@ -0,0 +1,75 @@
+# The scaffold, and what the platform holds it to
+```bash
+npx @jtakeit/astro create <slug> --name "The Business" --locale de-CH --vertical salon
+```
+Copies `template/`, fills in the tokens, names the copy module for the locale,
+writes a README and makes the first commit (`--no-git` to skip it). It decides
+nothing about how the site looks: every component is a starting point, and the
+contract below is the only thing the platform will hold the repository to.
+## The tokens
+| token | example |
+| --- | --- |
+| `{{SLUG}}` | `duckit` — the directory and the package name |
+| `{{NAME}}` | `DUCK IT` |
+| `{{LOCALE}}` | `de-CH` — the copy module's name, `src/copy/de-CH.ts` |
+| `{{LANG}}` | `de-CH` — `<html lang>` |
+| `{{OG_LOCALE}}` | `de_CH` |
+| `{{PHONE_REGION}}` | `CH` — the region `libphonenumber` parses the number in |
+| `{{SCHEMA_TYPE}}` | `LocalBusiness`, or `--schema-type HairSalon` |
+| `{{PREVIEW_URL}}` | `http://localhost:4321/` — where `astro dev` says it is; every build the platform makes passes `SITE_URL` |
+| `{{UI_*}}` | the form's and the privacy page's sentences in the site's language |
+An unreplaced `{{` anywhere in the tree is a scaffold bug; the package's smoke
+test fails on one.
+## The `jtk/` contract
+```
+jtk/catalogue.json    what the owner may edit — derived from src/content/blocks.ts by `jtk catalogue`
+jtk/content/*.json    the values, one document per page — the panel's, written by a publish
+jtk/bookings.json     the diary's settings, when the catalogue turns bookings on — seed it here
+jtk/design.json       the design document the panel reads for the editor's chrome
+```
+The repository decides what a site *is*; the panel fills in the values. A commit
+under `jtk/` **is** the published state, and a publish writes these files back.
+`import_branch` reads them into the panel after you commit; `publish` makes them
+what the preview offers.
+## The build contract
+The platform builds every commit in a container: `npm ci`, `npm run build`, the
+annotation lint over `dist/`, upload. Three flags arrive as environment, read as
+`import.meta.env`:
+| flag | what |
+| --- | --- |
+| `SITE_URL` | the site's address, `https://<host>/` — the canonical and the sitemap follow it; under the preview it carries a path, `/p/<slug>/`, and `astro.config.mjs` derives `base` from it |
+| `PUBLIC_INDEXABLE` | `true` once the site is launched; feeds the robots meta tag, `robots.txt` and the sitemap |
+| `PUBLIC_JTK_ANNOTATE` | whether `data-jtk-path` is emitted — always on; the edge strips it for visitors |
+`jtakeit-meta.mjs` writes `dist/_meta.json` beside the pages: the redirects and
+the unfinished entries, which the edge cannot read off a page.
+**The lockfile is pinned and committed.** `npm ci`, never `npm install`, in a
+site: the platform's runner bakes the scaffold's `node_modules` so a build takes
+twenty seconds rather than ninety, and a lockfile that drifted from the
+scaffold's is a build that installs from scratch.
+**There is no deploy.** The platform builds and serves; a site has no
+`wrangler`, no Pages Functions, no server code of its own. The form posts to
+`/api/lead` and the diary to `/api/availability`, `/api/book` and the rest, all
+of which the platform answers beside the site ([lead-form.md](lead-form.md),
+[booking.md](booking.md)).
+## Astro only
+Today Astro is the only generator the platform supports: collecting a
+collection's entries reads their frontmatter with the site's own Astro,
+pictures go through `astro:assets`, the flags are read as `import.meta.env`,
+and the runner's baked `node_modules` are this scaffold's. A repository on
+another generator does not build on the platform.

package/docs/shapes.md ADDED Viewed

@@ -0,0 +1,140 @@
+# The shapes a page can take
+Three catalogues: how the first screen is built, how the page is built under it,
+and how the type is paired. Pick one from each, deliberately, and **not the one
+the last project used**.
+This file exists because of a measurement. Three spec builds for three unrelated
+businesses — a massage practice, a manual therapist, a children's clinic — came
+out with the same hero, class for class:
+```
+section.hero > .hero__body > p.eyebrow  h1  p.hero__lead  p.hero__actions > a.btn + a.link
+                                                                         + div.hero__media
+```
+Different words, different palettes, different fonts, one page. Under it, all
+three were a stack of full-bleed bands — one of them literally names its
+sections `band band band band band band band band`. What varied was the skin and
+one bespoke component each.
+Nothing chose that. It is what you get when the only worked example in the
+documentation is a split hero, and the alternative would have had to be invented
+under time pressure. So the alternatives are written down here instead.
+## Hero anatomies
+| | What it is | Wants | Costs |
+| --- | --- | --- | --- |
+| **split** | Text column beside a media column. | A photograph worth half the screen and a headline that needs room. | It is our default and everybody else's — using it needs a reason, not a shrug. |
+| **overlay** | One full-bleed photograph; the words sit on it. | A genuinely good picture, and a scrim. | Contrast work in every frame, and the picture has to survive text across its middle. |
+| **typographic** | No photograph at all above the fold. The headline is the image. | A sentence strong enough to carry a screen, and type that has been chosen rather than picked. | Nowhere to hide: if the words are ordinary, the page opens on ordinary. |
+| **portrait-led** | The person is the hero and the words are its caption — inverted hierarchy, photograph dominant. | A soloist, and a frame of them worth looking at. | Fails badly on a weak portrait, which on the outbound track is common. |
+| **masthead** | A journal's top: kicker, rules, a headline across the full width, one dense row of facts, no media in the first screen. | A business whose credibility is the argument — clinics, legal, technical trades. | Reads as cold where warmth is the product. |
+| **object** | One thing — the work, the tool, the dish — centred and framed, text orbiting it. | A product, and a photograph that can be cut out or framed cleanly. | Needs a good silhouette; a busy background kills it. |
+| **pile** | Four or five photographs laid over each other, each a few degrees off square, the words beside them. `src/components/Pile.astro`. | A feed rather than a photograph — several usable frames and no outstanding one. | Reads as a collage past five cards, and as a mess if the cards have no edge: the overlap needs a hairline, a shadow or a plate to read as layers. |
+**`pile` is the answer to the row above it.** `portrait-led` fails on a weak
+portrait, and on the outbound track that is the ordinary case: a scraped feed
+often has no single frame that can carry a screen. A pile puts four on the
+screen so that none of them has to — the strongest use we have for material
+nobody would call good. `<Pile>` owns the arrangement because the fault it
+prevents is specific: a rotated card whose corner leaves the viewport takes the
+whole page sideways on a phone, which is what the site this was measured off
+ships with (393px viewport, 404px of page).
+Two rules across all seven. The one action stays inside the first screen unless
+the anatomy makes that dishonest (a masthead may legitimately put it one line
+below), and whatever the anatomy, `fl-check` still measures the fold, the wide
+screen and the crop.
+## Scattered, then square
+A tilt is worth something only against a straight edge.
+The composition this comes from reads as *photographs at an angle that then line
+up* — and there is no animation anywhere in it: the rotations are identical at
+the top of the page and a thousand pixels down. It is a pile in the hero and a
+grid under it, and the eye supplies the rest. That is the whole trick, and it
+costs no script, no scroll timeline, and nothing at all for a visitor with
+JavaScript off.
+So: **one register of the page tilts and the rest is set square.** The pile, or
+the one signature card, or the price list pinned to the wall — one of them, and
+everything around it on a straight line. A page where three unrelated things sit
+at three angles nobody chose does not read as casual, it reads as accidental.
+The magnitude is `--tilt`, and it is a token because it has to be the same
+number everywhere: ±3–6°, measured off the sites that do this well. Past about
+8° it stops being a hand and starts being a template. `data-tilt="left"` and
+`data-tilt="right"` are in surface.css — they set `rotate` rather than
+`transform`, so a tilted block can still be moved by an entrance.
+## Page forms
+The hero gets attention and the rest of the page gets copied. All three builds
+were a vertical stack of full-bleed bands with alternating backgrounds, which is
+one form out of several.
+- **band stack** — full-bleed sections, alternating grounds. Simple, safe, ours,
+  and recognisable from across the room as ours.
+- **shell** — everything inside one measure, sections as panels with air between
+  them, nothing full-bleed except perhaps a single photograph. Reads as a
+  document rather than as a landing page.
+- **two-rail** — one column scrolls, one stays: the photograph, the price card
+  or the contact details sit still while the argument moves past them. Wants a
+  wide screen and degrades to stacked on a phone.
+- **single scene** — one environment holds the whole page — their room, their
+  wall, one continuous photograph — with the content floating over it in
+  panels. The most memorable and the most demanding of the material.
+- **index** — the page is a list: services as rows, each with its own line and
+  price, like a menu or a treatment card. For a business whose customer already
+  knows what they want and is choosing *which*.
+- **letter** — one column, one voice, photographs interleaved. A letter from the
+  person who does the work. Wants a real writer's material — the captions of
+  someone who explains their craft — and nothing else on the page.
+## Type pairings
+Serif display over sans body is a good pairing and it was used in all three
+builds. It is one of six.
+- **serif display + sans body** — the default. Warm, editorial, safe.
+- **one grotesk** — a single family, contrast made from weight and size only.
+  Confident and modern; nowhere to hide a weak layout.
+- **all serif** — display serif over a text serif. Slow, human, expensive-looking.
+- **mono or technical display + humanist sans** — for trades that measure things.
+- **condensed display + wide body** — the tension is the point; strong for
+  posters and for food.
+- **system stack, deliberately, with one bought display face** — the fastest
+  page in the set, and it only works if the display face is genuinely good.
+Whatever the pairing: two families at most, both loaded from the same host,
+preconnect set. A third family is nearly always why mobile Lighthouse is at 84.
+## And what it is printed on
+Three catalogues decide what the page *is*. Three more decide what it is made
+of — the ground under the content, the edge its blocks are drawn with, and how
+they arrive — and they are in [surface.md](surface.md), with the same rule
+attached: not the one the last project used. A shape and a surface chosen
+together is a direction; either one alone is a skin.
+## Recording the choice
+## The one thing that cannot be reused
+A catalogue produces variety, not identity: seven anatomies over fifty projects is
+still eight sites that look like each other. So one element on every page has to
+be **impossible to move to another site** — made from this business's own
+material rather than from a component.
+Their handwriting off a caption, set as a heading. A photograph of their actual
+price card. The stripe of colour taken from their wall. Their sign, photographed
+and used as the wordmark. The tool they hold in every third post, cut out and
+used as the bullet.
+That is the difference between a page that is different and a page that is
+theirs, and it is the answer to "why does this not look like a template" that a
+client can see in one second.

package/docs/surface.md ADDED Viewed

@@ -0,0 +1,187 @@
+# The surface: grounds, edges and entrances
+Three catalogues, and one decision. The hero is where a page spends its loud
+moment — [hero-motion.md](hero-motion.md) is that. This is everything under it:
+the paper the page is printed on, the edge a block is drawn with, and how a
+block arrives when it is scrolled to.
+They are written down together because they are chosen together, and because
+each of them is a place where a page quietly acquires somebody else's taste. A
+ground picked because it was the example in this file is how fifty sites end up
+sharing a background.
+```jsonc
+// jtk/design.json — the surface, beside the palette
+"surface": {
+  "pattern": "rules",   // the ground. "" is none, and none is a choice
+  "scope": "page",      // one layer behind the document, or one per section
+  "opacity": 0.06,      // the volume knob. fl-check measures this one
+  "draw": false,        // a drawn ground sets itself out once
+  "edge": "corners",    // how a block is drawn
+  "reveal": "settle"    // how a block arrives
+}
+```
+Everything is a document rather than props typed into a page, for the same
+reason the copy is: it can be changed without an agent, and the studio bar's
+live accent drives it.
+## The grounds
+`src/components/surface/Pattern.astro`, figures in `patterns.ts` beside it.
+Six, and they are not six skins of one look — each does something the others
+cannot.
+| `pattern` | What it is | Wants | Costs |
+| --- | --- | --- | --- |
+| **none** | The token ground, and nothing else. | A page carrying strong photographs, where anything behind them is noise. | Nothing. It is chosen by leaving `pattern` empty, and it is a real choice — say it out loud rather than defaulting into it. |
+| `grain` | Film grain, paper fibre, plaster. No figure at all: its whole job is that a flat token stops reading as a fill. | Any page whose grounds are large and plain. It is the one that goes with everything. | Turned up, it is a grey wash rather than a texture. Under 0.1. |
+| `rules` | The ruled plane: ledger paper, a form, a chart. | Trades that measure — clinics, legal, technical, anything whose credibility is the argument. | Reads as cold where warmth is the product. |
+| `hatch` | Engraved hatching, one direction, the way a burin goes. | Print, craft, food, barbers, workshops. | On a busy page it fights the photographs. |
+| `contour` | Contour lines, the way a landscape is drawn. | Bodies and calm: massage, wellness, anything organic. | Needs height to read — in a 180px band you see two lines and a shrug. |
+| `construction` | Setting-out: axes, circles, dotted guides. The register of a studio that shows its process. | Studios, ateliers, anywhere the work is watched being made. | It is the loudest of the six, and it is not anybody's signature — see the last section. |
+| `motif` | The client's own mark, tiled: their tile, their fabric, their stamp, the shape off their sign. | Anywhere that mark exists. | **No default.** It does not build without the figure, and the figure is not in this repository. |
+Two mechanisms, because they do different work. `grain`, `rules` and `hatch`
+are **stencils** — a repeating figure with no beginning and no end, drawn as a
+CSS mask, no markup and no bytes past `patterns.ts`. `contour`, `construction`
+and `motif` are **drawings** — one composition that bleeds off its box, in SVG,
+because a figure has a size and a place and because strokes can draw themselves.
+### It is in their ink, or it is somebody else's page
+**A ground is a stencil and the ink is a token.** Nothing in `patterns.ts` names
+a colour. A stencil is an alpha mask over a layer painted in `--pattern-ink`; a
+drawing is line art in `currentColor`, which is the same token. So a variant
+that changes its palette repaints its ground with it, the live accent picker
+drives it, and a ground can never arrive in a colour somebody else chose — which
+is the failure a shipped background image makes inevitable.
+The volume is `--pattern-opacity`, and it is the property most likely to be set
+too high. A ground is read at a glance and never read *at*. `fl-check` composites
+the ink over the paper and fails the page above 1.6:1, because "is the texture
+too strong" is a question two people answer differently on two monitors and the
+contrast between figure and paper is a number.
+### Where the layer goes
+`scope="page"` pins one fixed layer behind the whole document — one composited
+surface, no repaint on scroll. It is only visible through sections that let it
+through: on a stack of full-bleed bands with their own backgrounds, half of them
+cover it. Use `scope="block"` there, on the sections that should carry it, and
+give each of those `class="has-pattern"` — two properties that make the section a
+stacking context, without which the layer disappears behind the band's own
+colour and looks exactly like a ground nobody added.
+### Every way it fails ends at the paper
+No JavaScript, no mask support, a printer, reduced motion: all of them end at
+the plain token ground, which is a design rather than a hole. Nothing readable is
+ever inside the layer, nothing is positioned against it, it is `aria-hidden`, and
+it is never the LCP element. A drawn ground with `draw` sets itself out once and
+stops; reduced motion gets the finished drawing, never a missing one.
+Unlike a hero field this costs no canvas and no script, which is why it is also
+the answer where WebGL is not available, and why a still of the page shows
+exactly what a visitor sees.
+### And the photographs on it
+A ground and the photographs printed on it are one decision. The fourth
+catalogue lives in [photos.md](photos.md) — six treatments, chosen once for the
+site in the same document — and the pairs that belong together are obvious once
+both are on the table: `grain` with `film`, `riso` or `hatch` with `press`,
+`construction` with an untouched photograph that has something to say.
+The rule there is the same shape as the one here: **one treatment per site**, and
+never a strong one on their face.
+## The edges
+Attributes, not wrappers: `<article class="card" data-edge="corners">`. Delete
+the attribute and the block is the block. Drawn on a pseudo-element rather than
+as a border, so adding an edge never changes a block's size and never fights the
+padding a design already settled.
+| `edge` | What it is |
+| --- | --- |
+| `none` | The edge is where the block's ground stops. |
+| `hairline` | One line. Everything else here is a departure from it. |
+| `stitch` | Dashed: sewn, ruled, provisional. |
+| `corners` | Crop marks — the corners drawn, the sides not. Registered rather than boxed. |
+| `notch` | A cut corner: a ticket, a label, a price tag. On the box itself, so the block needs a ground of its own to cut. |
+| `offset` | Two frames, one offset from the other, the outer in the accent. A poster's register. |
+| `trace` | The perimeter draws itself once, clockwise from the top, as the block arrives. |
+| `sweep` | A light travelling around the edge, forever. |
+| `lift` | The block answers the hand: shadow and a couple of pixels on hover and focus. |
+Two rules, and `fl-check` holds the page to both:
+- **An animated edge belongs to something that can be pressed.** Furniture that
+  performs is furniture being looked at instead of the words.
+- **One thing on a page moves forever**, and the hero has usually already spent
+  it. `sweep` on six cards is not a design, it is a component gallery.
+`offset` draws its outer frame as an `outline`, which is also how a focus ring
+is drawn — keep it on blocks rather than on anything focusable.
+## The entrances
+Also attributes: `data-reveal`. The hidden start state hangs on `html.js`, which
+the layout sets before first paint, so a visitor with JavaScript off gets the
+finished page rather than a column of invisible sections. The observer that adds
+`.is-in` is in `Layout.astro`; it watches each block once and never again.
+| `reveal` | What it is | Wants |
+| --- | --- | --- |
+| `none` | The page is already there. | Short pages, and any page where the entrance was the only idea. |
+| `rise` | Up and in. The default, and the one every site has. | A page with a handful of large blocks. |
+| `settle` | Fades and settles a little closer, with no travel. | A dense page: travel makes a long column feel like it is bouncing. |
+| `wipe` | Uncovered from one edge rather than moved. | A graphic page, a print register, anything already linear. |
+| `develop` | Out of focus, then not. Photographic. | Pages carrying photographs — put it on the picture, not on the section around it. |
+| `stagger` | The children in order. `--i` is set by the observer, so a list rendered from a document does not carry an index into its markup. | Grids, price lists, an `index` page form. |
+| `draw` | Line art draws itself. Every figure needs `pathLength="1"`, and then one rule covers a circle, a line and a 56-point contour alike. | A page whose signature is drawn rather than photographed. |
+Three rules:
+- **One entrance per page.** Two is defensible where the second is on the
+  photographs. Three is a component gallery, and `fl-check` fails it.
+- **Nothing in the first screen is revealed.** It delays the largest paint and
+  shows a visitor on a slow line an empty page. Reveal what is scrolled to,
+  never what is landed on.
+- **It never replays.** A block that animates again on the way back up is what
+  clients report as "it keeps flashing".
+`Blocks.astro` gives the band immediately under the hero no entrance at all, for
+the second of those rules: on a phone, and on any page whose hero is not a full
+screen, that band is *in* the first screen. A design that replaces the component
+keeps the exception — or gives the hero the height that makes it unnecessary.
+Reduced motion means the finished state everywhere: the block in place, the
+border closed, the drawing complete.
+**`hold` is not in this list on purpose.** A column that stays while the argument
+scrolls past it is `position: sticky` — it is the `two-rail` page form in
+[shapes.md](shapes.md), a layout decision, not an entrance. Putting it here
+would let a page pick it instead of choosing a shape.
+## Recording the choice
+## A catalogue is not an identity
+This file makes it cheap to look designed, and that is exactly its risk: the
+easier a page is to finish, the less likely anybody makes the one element that
+could not be moved to another site.
+`construction` is the case to be careful with. It exists because a build had its
+own construction geometry — the guides one tattooist leaves in red inside her own
+work, redrawn as the furniture of her page — and that was the best thing on the
+site. What is in `patterns.ts` is the generic article, not her drawing. Using it
+buys a register; it does not buy a signature.
+`motif` is the entry that does. It has no default, it does not build without the
+figure, and the figure is theirs: their tile, their stamp, their sign, their
+handwriting. If a page's whole visual identity is three values out of these
+tables, it is a page that is different from the last one rather than a page that
+is theirs — see the last section of [shapes.md](shapes.md).