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/template/src/content.config.ts ADDED Viewed

@@ -0,0 +1,19 @@
+import { defineCollection } from 'astro:content';
+import { COLLECTIONS } from './content/blocks';
+import { entries } from './lib/entryLoader';
+/**
+ * The collections this site has, read from the one place that declares them.
+ *
+ * `src/content/blocks.ts` says which collections exist — that file is the
+ * catalogue, and the admin draws its screens from the same declaration. This
+ * derives the Astro side of it rather than repeating it, so adding a collection
+ * is one entry in one array and never two lists that drift.
+ *
+ * The reading itself is `entryLoader.ts`, and its header is where the argument
+ * lives: an entry is a document of blocks now, so the prose is a string that
+ * has to go through the markdown pipeline rather than a file Astro can glob.
+ */
+export const collections = Object.fromEntries(
+  COLLECTIONS.map((collection) => [collection.name, defineCollection({ loader: entries(collection) })]),
+);

package/template/src/copy/LOCALE.ts ADDED Viewed

@@ -0,0 +1,324 @@
+/**
+ * Every sentence a visitor reads — read from `jtk/content/index.json`
+ * rather than written here.
+ *
+ * The strings live in the repository's content document so that the studio's
+ * admin can edit them: a commit under `jtk/` **is** the published state,
+ * and publishing writes that file. This module is the adapter between that
+ * document and the shape the components already import, which is why the
+ * exports below look ordinary — nothing in a component has to know where its
+ * text came from.
+ *
+ * Two things did not move, because they are not content:
+ *   META  — the `<html lang>` value and the title suffix
+ *   A11Y  — the skip link
+ *
+ * Comments and identifiers stay English. The values are the client's language.
+ *
+ * ── the document, and the file that ships with this scaffold ────────────────
+ *
+ * `jtk/content/index.json` is committed with empty strings in it, and that
+ * is deliberate: a fresh project must `npm run build` on a laptop the minute
+ * `fl-init` finishes, and a static import of a file that is not there is a build
+ * error rather than an empty page. The first publish from the admin replaces it
+ * wholesale.
+ *
+ * `jtk/catalogue.json` is **not** shipped. It describes what blocks a site
+ * has, the admin seeds it from the registry on the first publish, and a copy
+ * here would be a second one to keep in step by hand.
+ */
+import page from '../../jtk/content/index.json';
+import { LOCALE } from '../content/blocks';
+export const META = {
+  /**
+   * The `<html lang>` value and `inLanguage` in structured data.
+   *
+   * From `LOCALE` in `src/content/blocks.ts`, not written again here: that file
+   * is what declares the site's languages to the platform, and a language
+   * spelt in two places is a language that is eventually spelt two ways.
+   */
+  lang: LOCALE,
+  /** `og:locale`, e.g. uk_UA, de_CH, en_GB. */
+  ogLocale: '{{OG_LOCALE}}',
+  /** Appended to every page title except the home page's. */
+  titleSuffix: ' — {{NAME}}',
+} as const;
+/**
+ * What the site says on its own behalf, rather than what the business says.
+ *
+ * Written by `fl-init` from the locale, not left blank: a skip link with no
+ * words is a skip link a screen reader announces as nothing.
+ */
+/**
+ * The privacy page's words.
+ *
+ * Short on purpose, and shorter than it was. What the **platform** does with an
+ * enquiry — how long it keeps it, where — used to be six paragraphs here, in
+ * every language a site is ever built in, going stale the day any of it
+ * changed. It is one link now, and the text lives where the thing it describes
+ * lives.
+ *
+ * What is left is the business's own: what their form asks for, that the site
+ * runs on somebody, and how to reach them. The heading under `ownTitle` is left
+ * empty for whoever is building the site — a generated paragraph about somebody
+ * else's company is a guess wearing a legal shape.
+ *
+ * **None of it is required.** The platform asks for one link on a page that
+ * opens and reads nothing around it; these words are a default so that a new
+ * site has something true on day one, not a form anybody has to keep to.
+ */
+export const PRIVACY = {
+  title: '{{UI_PRIVACY_TITLE}}',
+  intro: '{{UI_PRIVACY_INTRO}}',
+  formTitle: '{{UI_PRIVACY_FORM_TITLE}}',
+  formBody: '{{UI_PRIVACY_FORM_BODY}}',
+  /** Ends in a colon: the link follows it. */
+  whoTitle: '{{UI_PRIVACY_WHO_TITLE}}',
+  whoBody: '{{UI_PRIVACY_WHO_BODY}}',
+  askTitle: '{{UI_PRIVACY_ASK_TITLE}}',
+  askBody: '{{UI_PRIVACY_ASK_BODY}}',
+  /** The business's own section. Empty on purpose: it is theirs to write. */
+  ownTitle: '{{UI_PRIVACY_OWN_TITLE}}',
+} as const;
+export const A11Y = {
+  skipToContent: '{{UI_SKIP_TO_CONTENT}}',
+} as const;
+type Block = Record<string, unknown> & { type: string };
+type Item = Record<string, unknown>;
+const blocks = page.blocks as unknown as Block[];
+/**
+ * A block by type, with its index.
+ *
+ * The index is what an annotation path is built from, so it has to come from the
+ * document rather than be counted by hand in the markup — a block inserted above
+ * this one moves it, and a hand-written path would then point at somebody else's
+ * text.
+ *
+ * A block the document does not have is not an error: the admin can remove one,
+ * and a page that threw at build time because a section was deleted would make
+ * removing a section a deploy incident.
+ */
+export function block(type: string): { at: number; of: Block } {
+  const at = blocks.findIndex((candidate) => candidate.type === type);
+  return at === -1 ? { at: -1, of: { type } } : { at, of: blocks[at]! };
+}
+export const str = (of: Block, key: string): string => (of[key] as string) ?? '';
+export const rows = (of: Block, key: string): Item[] => (of[key] as Item[]) ?? [];
+/**
+ * One picture of a gallery, as a component wants it.
+ *
+ * `name` is what `<Shot>` resolves — a slot in `src/assets` for a picture the
+ * repository ships, or a key like `media/<site>/<hash>.jpg` for one the owner
+ * uploaded. Both are local files by build time and both go through
+ * `astro:assets`; nothing downstream has to know which it was given.
+ */
+export interface Shown {
+  readonly name: string;
+  readonly alt: string;
+  /** `data-jtk-path` for this picture: `blocks[3].work[7].src`. */
+  readonly path?: string;
+  /** A clip's poster — the still every refused autoplay lands on. */
+  readonly poster?: string;
+}
+/**
+ * One picture of a block, as a component wants it.
+ *
+ * ── every photograph on the page is one of two things ───────────────────────
+ *
+ * A gallery item, or a field of its own. There is no third kind, and the
+ * difference is not how it is stored — it is what an owner can do about it.
+ * A photograph that is neither is a photograph only we can change, and "can you
+ * swap the picture of me" becomes a message and a deploy.
+ *
+ * So the rule is: **a photograph that is on the page on purpose gets a field.**
+ * Declare it, put the slot it already uses in the content document, and pass
+ * the path to `<Shot>`:
+ *
+ *   const { at, of } = block('artist');
+ *   const portrait = picture(of, at, 'portrait');
+ *   <Shot name={portrait.name} alt={portrait.alt} path={portrait.path} ratio="4 / 5" />
+ *
+ * The value stays the slot the repository already ships — `artist-at-work` —
+ * so nothing about the page changes until somebody chooses to change it.
+ *
+ * The alt text is a sibling field, `<key>_alt`, marked `no_tap_target`: a media
+ * field's value is one string with nowhere to keep words, and there is nothing
+ * on the page that *is* the alt text to tap. (A gallery item keeps its own alt
+ * inside it, because a collection has room for one.)
+ *
+ * What stays out: a photograph that is structure rather than subject — a
+ * texture, a rule, a shape behind a heading. That is design, and the catalogue
+ * is the place where the difference is written down.
+ */
+export function picture(of: Block, at: number, key: string): Shown {
+  return {
+    name: str(of, key),
+    alt: str(of, `${key}_alt`),
+    path: pathAt(at, key),
+  };
+}
+/**
+ * A gallery field, as pictures.
+ *
+ * ── this function is the seam ───────────────────────────────────────────────
+ *
+ * The catalogue declares one field holding many pictures; the document stores
+ * them as `[{ src, alt }]`, in the order they appear on the page; the admin
+ * annotates each one at `blocks[3].work[7].src`. All three of those facts live
+ * here and nowhere else, so a component takes a list and renders it:
+ *
+ *   const { at, of } = block('plates');
+ *   <Gallery arrangement="wall" items={gallery(of, at, 'work')} />
+ *
+ * **Every picture carries its own path.** That is the half that cannot be
+ * skipped: without it the owner sees their work on the page and cannot touch
+ * it, `fl-catalogue` fails on exactly that, and a gallery is the longest list
+ * on the site to have to fix afterwards.
+ *
+ * A field the document does not have is an empty list rather than an error. It
+ * is what a site looks like on a laptop before it has ever been attached, and a
+ * build that threw there could not be checked or pushed.
+ */
+export function gallery(of: Block, at: number, key: string): Shown[] {
+  return rows(of, key).flatMap((item, i) => {
+    const src = (item.src as string) ?? '';
+    if (!src) return [];
+    return [
+      {
+        name: src,
+        alt: (item.alt as string) ?? '',
+        poster: (item.poster as string) || undefined,
+        path: pathAt(at, key, i, 'src'),
+      },
+    ];
+  });
+}
+/**
+ * The path of a field, for `data-jtk-path`.
+ *
+ * Returns undefined when annotations are off, so Astro drops the attribute
+ * entirely and a production build carries no trace of the editor — the same
+ * switch the build contract calls PUBLIC_JTK_ANNOTATE.
+ *
+ * **Every element whose text or image comes from content must carry one.** That
+ * is not a convention: the annotation lint fails the build without it, because
+ * an element that loses its path stops opening the editor *silently*, and
+ * nobody finds out for a week.
+ */
+const ANNOTATE = import.meta.env.PUBLIC_JTK_ANNOTATE !== 'false';
+export function flPath(
+  type: string,
+  field: string,
+  item?: number,
+  subField?: string,
+): string | undefined {
+  if (!ANNOTATE) return undefined;
+  const { at } = block(type);
+  if (at === -1) return undefined;
+  return item === undefined
+    ? `blocks[${at}].${field}`
+    : `blocks[${at}].${field}[${item}].${subField}`;
+}
+/**
+ * Every block, in the document's own order.
+ *
+ * The page renders this rather than looking blocks up by name, because a page is
+ * a sequence and a generated one repeats types: two feature grids and three
+ * prose sections are an ordinary landing page, and `block('feature_grid')` can
+ * only ever find the first.
+ *
+ * The index is the block's own, which is what an annotation path is built from.
+ */
+export const PAGE: readonly Block[] = blocks;
+/** The path of a field on the block at `at`, for `data-jtk-path`. */
+export function pathAt(at: number, field: string, item?: number, subField?: string): string | undefined {
+  if (!ANNOTATE) return undefined;
+  if (at < 0 || at >= blocks.length) return undefined;
+  return item === undefined
+    ? `blocks[${at}].${field}`
+    : `blocks[${at}].${field}[${item}].${subField}`;
+}
+const hero = block('hero').of;
+const cta = block('cta_banner').of;
+export const HOME = {
+  /** Complete on its own — the home page passes suffix={false}. */
+  title: (page.seo?.title as string) ?? '',
+  /** ~150–160 characters, a sentence a person would read in a result list. */
+  description: (page.seo?.description as string) ?? '',
+  hero: {
+    eyebrow: str(hero, 'eyebrow'),
+    heading: str(hero, 'title'),
+    lead: str(hero, 'lead'),
+    cta: str(hero, 'cta_label'),
+    ctaHref: str(hero, 'cta_href') || '#contact',
+    image: str(hero, 'image'),
+    imageAlt: str(hero, 'image_alt'),
+  },
+} as const;
+/**
+ * The lead form.
+ *
+ * Its labels belong to the business; its validation strings are interface, and
+ * the catalogue marks those `client_editable: false` — there is nothing a
+ * business owner wants to say in "Sending…".
+ *
+ * Which is why `fl-init` writes them from the locale rather than leaving them
+ * blank. They were blank, in every language, and the form said nothing while
+ * it sent, nothing when it had sent, and nothing when a field was empty — a
+ * defect that no build catches, because an empty string is a valid string.
+ *
+ * Server-side validation has its own copy on the platform, behind `/api/lead`: the
+ * browser never sees those strings until the server answers, so they cannot be
+ * shared from here.
+ */
+export const FORM = {
+  title: str(cta, 'title'),
+  lead: str(cta, 'lead'),
+  // The questions, which are the business's own — see blocks.ts.
+  name: str(cta, 'name_label'),
+  contact: str(cta, 'contact_label'),
+  message: str(cta, 'message_label'),
+  required: '{{UI_REQUIRED}}',
+  requiredNote: str(cta, 'required_note'),
+  privacy: '{{UI_PRIVACY}}',
+  submit: str(cta, 'cta_label'),
+  sending: '{{UI_SENDING}}',
+  success: '{{UI_SUCCESS}}',
+  error: '{{UI_ERROR}}',
+  invalidName: '{{UI_INVALID_NAME}}',
+  invalidContact: '{{UI_INVALID_CONTACT}}',
+  invalidMessage: '{{UI_INVALID_MESSAGE}}',
+  /** Shown while the Telegram bot is not connected. Preview only. */
+  demoNote: '{{UI_DEMO_NOTE}}',
+} as const;

package/template/src/data/site.ts ADDED Viewed

@@ -0,0 +1,137 @@
+import { under } from '../lib/under';
+/**
+ * {{NAME}} — the business's own facts, and the one switch that controls
+ * indexability.
+ *
+ * Nothing here is copy. It is the data that appears in structured data, in the
+ * footer, in `tel:` links, in the sitemap and in llms.txt, and it must be
+ * identical everywhere it is rendered — which is why it is rendered from here
+ * and never typed into a component.
+ *
+ * Only confirmed facts. Everything on this page is asserted to Google, and to
+ * the assistants that quote it, as fact: a wrong opening hour or an invented
+ * rating is worse than a missing one, and it carries the client's name.
+ */
+/**
+ * The host this build claims, read back from the `site` option in
+ * astro.config.mjs rather than written down a second time. A preview build sets
+ * SITE_URL there and every canonical link follows it.
+ */
+export const SITE_URL = import.meta.env.SITE;
+/**
+ * Whether the robots meta tag, robots.txt, the sitemap and llms.txt say
+ * "index me". Always: there is nothing here to decide.
+ *
+ * On the platform there is one kind of build, made for the site's address.
+ * The preview shows the same build under `/p/<slug>/`, behind a session,
+ * and the platform itself keeps it out of the index with a header; the
+ * launch moves a pointer. A switch in this file that somebody flipped at
+ * launch was the shape that shipped sites telling search engines to go away,
+ * and a build that says noindex is refused (JTK_E_NOINDEX). The constant
+ * stays so the four files that read it keep one name for one fact.
+ */
+export const INDEXABLE = true;
+export const BUSINESS = {
+  name: '{{NAME}}',
+  /** One sentence: what this business is, where, for whom. */
+  description: '',
+  /** Address in parts. A single string is not parseable by anything. */
+  street: '',
+  postalCode: '',
+  city: '',
+  region: '',
+  /** ISO 3166-1 alpha-2. */
+  country: '',
+  /** What a visitor reads — the form the local market recognises. */
+  phoneDisplay: '',
+  /** What a phone dials. E.164. Never the same string as the one above. */
+  phoneDial: '',
+  email: '',
+  /** Every profile that is really theirs. Feeds `sameAs`. */
+  instagram: '',
+  facebook: '',
+  /** Google's coarse bucket, e.g. '€€' or 'CHF 3–130'. Not a price list. */
+  priceRange: '',
+  mapsUrl: '',
+} as const;
+/**
+ * The one query this page is for: **[service] [city]**.
+ *
+ * Not a keyword list. One service, named the way a customer would say it out
+ * loud, and the city they would say it in. A landing page that tries to rank
+ * for six things ranks for none of them, and a business with several services
+ * gets one page per service later — not six phrases on this one.
+ *
+ * Nothing renders this. It is the target the copy is written *at*, and
+ * `fl-check` reads it back to confirm that the title, the h1 and the
+ * description actually serve it — a page that has to have the phrase inserted
+ * to pass the check has already missed the point.
+ *
+ * The page still has to read as though written for a person: the query belongs
+ * in sentences about this business and this person, and the moment it is
+ * repeated for the crawler's benefit it is working against both audiences. See
+ * `docs/pages.md` of @jtakeit/astro.
+ */
+export const SEARCH: {
+  /** What a customer types. Their word, not the trade's. */
+  service: string;
+  /** The city, as a customer names it. Empty where the business is not local. */
+  city: string;
+  /**
+   * The other forms of those two words that the copy legitimately uses.
+   * Ukrainian, German and Polish all decline: «Львів» is «у Львові» in the one
+   * sentence where it reads naturally, and a check that does not know that
+   * would report a correctly written page as missing its city.
+   */
+  forms: readonly string[];
+} = {
+  service: '',
+  city: '',
+  forms: [],
+};
+/**
+ * The narrowest schema.org type that is true — Restaurant, NailSalon, Dentist,
+ * LegalService, HomeAndConstructionBusiness… A wrong narrow type is worse than
+ * a correct broad one; `LocalBusiness` is always honest.
+ */
+export const SCHEMA_TYPE = '{{SCHEMA_TYPE}}';
+/**
+ * Every page of the site, written by hand rather than generated, so that adding
+ * a page and forgetting to list it is a visible omission in one file instead of
+ * a silent one across the build. Feeds the sitemap and llms.txt.
+ */
+export const PAGES: readonly { path: string; priority: number; summary: string }[] = [
+  { path: '/', priority: 1.0, summary: '' },
+];
+export const fullAddress = [
+  BUSINESS.street,
+  [BUSINESS.postalCode, BUSINESS.city].filter(Boolean).join(' '),
+]
+  .filter(Boolean)
+  .join(', ');
+/**
+ * The site's origin, then the path under this build's base. `SITE` already
+ * carries the base on a preview build — `https://preview…/p/<slug>` — so
+ * resolving `under(path)` against it wrote the slug twice, and resolving the
+ * bare path against it dropped the slug. The origin is the one part of it
+ * that is the same in both readings.
+ */
+export function canonicalFor(path: string): string {
+  return new URL(under(path), new URL(SITE_URL).origin).href;
+}