@unitninety/site-kit 0.0.0-stage → 1.6.2

package/src/legacy/defineSite.types.ts

@@ -0,0 +1,270 @@
+/**
+ * Compile-only assertions about what `defineSite` infers.
+ *
+ * There is no test framework here and type errors do not surface at runtime, so these are
+ * asserted the only way types can be: this file must typecheck, and the lines marked
+ * `@ts-expect-error` must not. `pnpm typecheck` fails either way round — an unused
+ * `@ts-expect-error` is itself an error.
+ */
+
+import {
+  array,
+  block,
+  blocksField,
+  collection,
+  defineSite,
+  form,
+  group,
+  link,
+  number,
+  relationship,
+  richText,
+  select,
+  textField as text,
+  upload,
+} from './index'
+
+text({ localized: false })
+richText({ localized: false })
+// @ts-expect-error numeric facts are structurally shared, not localizable copy
+number({ localized: false })
+
+const lexical = { root: { children: [], type: 'root' } }
+
+const site = defineSite({
+  hero: block({
+    headline: text('Building Western Australia.'),
+    slides: array({ sector: text() }, [{ sector: 'Urban Development' }]),
+    /** Declared for the client to fill, committed by nobody — see the assertions below. */
+    gallery: array({ caption: text() }),
+  }),
+  /**
+   * A block a site publishes without seeding: every field is a slot, none is committed.
+   *
+   * One of each helper that builds its descriptor its own way rather than through `Scalar`'s
+   * shared body, since each is its own chance to answer the wrong thing.
+   */
+  pageBody: block(
+    {
+      heading: text(),
+      photo: upload(),
+      align: select({ options: ['left', 'right'] }),
+      /**
+       * A zone is created empty and commits nothing, which is the *normal* case for it — and
+       * the last helper with no line of its own here. `Aggregate` decides a group is absent
+       * by testing every member against `undefined`, so a helper answering `Unnamed<unknown>`
+       * instead makes any group holding one read as present while the runtime has nothing
+       * there. Every other helper is pinned below; without this line `blocksField` could
+       * regress to that and only a site would find out.
+       */
+      body: blocksField({ blocks: [] }),
+    },
+    { seed: false },
+  ),
+  banner: block({
+    cta: link({ default: { href: '/contact-us', label: 'Talk to us' } }),
+    /** No committed button: five children, none of which carries anything. */
+    secondary: link(),
+  }),
+  panel: block({
+    /**
+     * A page reference beside a caption the client fills in — an ordinary block shape, and
+     * the one that caught `relationship` answering `unknown`. Nothing here is committed, so
+     * the group is absent at runtime; the crash would land on `related`, not on `caption`.
+     */
+    related: group({ fields: { page: relationship({ relationTo: 'pages' }), caption: text() } }),
+    /** The same shape with one committed child: that child really is there, so it is typed. */
+    feature: group({
+      fields: { page: relationship({ relationTo: 'pages' }), caption: text('Our team at work.') },
+    }),
+  }),
+  contact: block({
+    /** One child committed, one not. */
+    address: group({ fields: { street: text('123 Main St'), suburb: text() } }),
+    /** No child committed: the group itself is what is missing, not just its children. */
+    hours: group({ fields: { open: text(), close: text() } }),
+  }),
+  story: block({
+    /** Bare copy: a string, like every other scalar. */
+    intro: richText('We have been building since 1974.'),
+    /** Stored one way, rendered another: the *rendered* form is what a component reads. */
+    body: richText({ default: lexical, value: 'Two paragraphs of it.' }),
+    /** Rendered as a document: the site reads the document back, not a string. */
+    note: richText({ value: lexical }),
+  }),
+  projects: collection(
+    { name: text(), image: upload() },
+    {
+      titleField: 'name',
+      rows: [{ name: 'Port Coogee', image: '/media/port-coogee.webp' }],
+    },
+  ),
+  logo: { ratio: 241 / 105, src: '/brand/logo-mark.png' },
+  /** A form commits no copy — see the assertion below. Same shape `syncForms` reads off it. */
+  contactForm: form({
+    fields: [{ label: 'Email', name: 'email', type: 'email', role: 'email' }],
+    label: 'Contact',
+  }),
+})
+
+export const brand = site.values
+export type Brand = typeof brand
+
+const headline: string = brand.hero.headline
+const sector: string = brand.hero.slides[0]!.sector
+const street: string = brand.contact.address.street
+const ratio: number = brand.logo.ratio
+const first: string = brand.projects[0]!.name
+const intro: string = brand.story.intro
+const body: string = brand.story.body
+const note: unknown = brand.story.note.root
+
+/*
+ * A bare entry is carried through with its own type, not widened to `unknown`.
+ *
+ * Both halves are the assertion: `unknown` would fail the annotation on `ratio` above, and
+ * this line is what says the type is `number` in particular rather than something a `string`
+ * would also satisfy.
+ */
+// @ts-expect-error a bare entry keeps the type it was written with
+const wrong: string = brand.logo.ratio
+
+// @ts-expect-error a key that was never declared does not exist on the inferred type
+const missing = brand.hero.subheadline
+
+/**
+ * A form commits no copy to `site.values` — there is nothing for a component to render,
+ * only a schema the platform validates submissions against and a mailing list it seeds
+ * once. `defineSite`'s loop diverts a `form()` entry into `forms` and never writes
+ * `values[key]`, exactly as it does for a layout; this pins that a form key reads the same
+ * way a layout key does, `TS2339` rather than a compiling `undefined`.
+ */
+// @ts-expect-error a form key does not exist on site.values — see `contactForm` above
+const noForm = brand.contactForm
+
+// @ts-expect-error a group's children are read through their own carriers, not as EditorField[]
+const nested: number = brand.contact.address.street
+
+/**
+ * A field nobody committed reads as `undefined`, not as the type it would have had.
+ *
+ * This is the half of the bargain a hand-written `Brand` got right by saying `heading?:
+ * string`. A generated type that answered `string` here would compile
+ * `brand.pageBody.heading.trim()` — which throws, on the fallback-render path this whole
+ * document exists to keep working. Each of these needs a guard to be read, which is the
+ * assertion: the type admits nothing until the caller has checked.
+ */
+const uncommitted: undefined = brand.pageBody.heading
+
+// @ts-expect-error an uncommitted scalar is not silently the type it would have had
+const assumed: string = brand.pageBody.heading
+
+// @ts-expect-error nor is it dereferenceable without a guard — this is the crash, caught
+const trimmed = brand.pageBody.heading.trim()
+
+/**
+ * An array with no committed items is `undefined`, not `[]`.
+ *
+ * The sharpest of them, because the reader is a `.map()` rather than a property access.
+ * `defineSite` writes no empty list here and must not: a declared-but-uncommitted array
+ * genuinely holds nothing, and a site that means an empty one writes `array(fields, [])`.
+ * Contrast the collection below, where `rows ?? []` makes `[]` true in both the type and the
+ * runtime.
+ */
+const noItems: undefined = brand.hero.gallery
+
+// @ts-expect-error mapping an array nobody committed is the TypeError this type now refuses
+const mapped = brand.hero.gallery.map(String)
+
+/** The helpers that build their own descriptor answer the same way. */
+const noPhoto: undefined = brand.pageBody.photo
+const noChoice: undefined = brand.pageBody.align
+const noZone: undefined = brand.pageBody.body
+
+// @ts-expect-error an empty zone is absent, not a list of sections waiting to be mapped
+const zoned = brand.pageBody.body.map(String)
+
+/** A committed button is read back as written; an uncommitted one is not there at all. */
+const href: string = brand.banner.cta.href
+const label: string = brand.banner.cta.label
+const noButton: undefined = brand.banner.secondary
+
+// @ts-expect-error a link nobody committed has no href to read
+const missingHref = brand.banner.secondary.href
+
+/** A group commits what its children commit — per child, and not at all when none do. */
+const committedChild: string = brand.contact.address.street
+const uncommittedChild: undefined = brand.contact.address.suburb
+const noChildren: undefined = brand.contact.hours
+
+// @ts-expect-error a group whose children all carry nothing is absent, not an empty object
+const reached = brand.contact.hours.open
+
+/**
+ * A reference commits nothing, so it counts as absent rather than as unreadable.
+ *
+ * The distinction is the whole of it. A member typed `unknown` refuses every dereference of
+ * *itself*, but it also makes the group around it look present — and then the crash lands on
+ * the group, one level above where anything could refuse it.
+ */
+const noReference: undefined = brand.panel.related
+
+// @ts-expect-error a group of an uncommitted reference and an uncommitted caption is not there
+const captionOfNothing = brand.panel.related.caption
+
+/** One committed child is enough to make the group present — and only that child is typed. */
+const featureCaption: string = brand.panel.feature.caption
+const featurePage: undefined = brand.panel.feature.page
+
+/**
+ * A collection declared without rows still reads as a list, never as `undefined`.
+ *
+ * `defineSite` writes `rows ?? []`, so the type and the runtime agree: a site that has
+ * declared the record type but committed no rows maps over an empty array rather than
+ * crashing on a property of `undefined`.
+ */
+const empty = defineSite({
+  team: collection({ name: text() }, { titleField: 'name' }),
+}).values.team
+const count: number = empty.length
+
+// @ts-expect-error rich text rendered as a document is not silently a string
+const flattened: string = brand.story.note
+
+export const used = [
+  headline,
+  sector,
+  street,
+  ratio,
+  first,
+  intro,
+  body,
+  note,
+  wrong,
+  missing,
+  noForm,
+  nested,
+  flattened,
+  count,
+  uncommitted,
+  assumed,
+  trimmed,
+  noItems,
+  mapped,
+  noPhoto,
+  noChoice,
+  noZone,
+  zoned,
+  href,
+  label,
+  noButton,
+  missingHref,
+  noReference,
+  captionOfNothing,
+  featureCaption,
+  featurePage,
+  committedChild,
+  uncommittedChild,
+  noChildren,
+  reached,
+]

package/src/legacy/draft.tsx

@@ -0,0 +1,128 @@
+'use client'
+
+import React from 'react'
+
+import { useHasMounted, useIsFramed } from './bridge'
+
+/**
+ * The bar that says "you are looking at a draft, and nobody else is".
+ *
+ * Draft mode is a cookie, and cookies are invisible. Without this, the only signal that
+ * a browser is reading staged content instead of the live site is that the content
+ * looks wrong — which reads as "the site published something I never approved", because
+ * from the operator's side that is exactly what it looks like. This is the missing half
+ * of `createExitPreviewRoute`: one tells you, the other lets you leave.
+ *
+ * Render it from the site's root layout, behind the server's own draft check:
+ *
+ *   const { isEnabled } = await draftMode()
+ *   ...
+ *   {isEnabled ? <DraftNotice /> : null}
+ *
+ * **Hidden inside the dashboard's Canvas frame.** There, a draft is the entire point and
+ * a bar would be noise sitting over the surface the client is editing. This component waits
+ * until hydration before drawing anything, so `useIsFramed` can perform its reliable mounted
+ * check without painting the public-preview bar for one commit inside Canvas.
+ *
+ * `position: fixed` so it takes no space in the document. Canvas measures elements in
+ * the frame to place its selection overlays, and a bar that pushed the page down by its
+ * own height would put every one of those overlays out by that much.
+ *
+ * Inline styles, deliberately: the kit cannot assume the consuming site's Tailwind
+ * content glob reaches into `node_modules`, and a bar styled with classes that were
+ * never generated is an invisible warning.
+ */
+export const DraftNotice = ({
+  /** Where the exit route is mounted, if a site moves it. */
+  exitPath = '/api/exit-preview',
+  label = 'Viewing staged changes — visitors still see the published site.',
+}: {
+  exitPath?: string
+  label?: string
+} = {}) => {
+  const framed = useIsFramed()
+  const hydrated = useHasMounted()
+
+  if (!hydrated || framed) return null
+
+  /*
+   * The page you are on is read at click time rather than baked into the href.
+   *
+   * A layout has no pathname to render into the link, and the obvious fix — fill it in
+   * after mount — is wrong twice over: it sets state from an effect, and it goes stale
+   * the moment the visitor navigates client-side, so Exit would return them to whatever
+   * page they first landed on. Reading `location` in the handler is always current.
+   *
+   * The plain `href` stays as the no-JS path; it just returns you to the home page.
+   */
+  const exitHere = (event: React.MouseEvent<HTMLAnchorElement>) => {
+    // Let ⌘-click, middle-click and the rest keep their normal meaning.
+    if (event.defaultPrevented || event.metaKey || event.ctrlKey || event.shiftKey) return
+    event.preventDefault()
+    const here = window.location.pathname + window.location.search
+    window.location.href = `${exitPath}?to=${encodeURIComponent(here)}`
+  }
+
+  return (
+    <div
+      role="status"
+      style={{
+        bottom: 'max(16px, env(safe-area-inset-bottom))',
+        display: 'flex',
+        justifyContent: 'center',
+        left: 0,
+        // The bar itself is the only thing clickable; the rest of this strip is not.
+        pointerEvents: 'none',
+        position: 'fixed',
+        right: 0,
+        zIndex: 2147483000,
+      }}
+    >
+      <div
+        style={{
+          alignItems: 'center',
+          background: '#111111',
+          border: '1px solid #333333',
+          boxShadow: '0 2px 12px rgba(0, 0, 0, 0.35)',
+          color: '#f5f5f5',
+          display: 'flex',
+          fontFamily:
+            'ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, Helvetica, Arial, sans-serif',
+          fontSize: '13px',
+          gap: '14px',
+          lineHeight: 1.3,
+          margin: '0 16px',
+          maxWidth: 'calc(100vw - 32px)',
+          padding: '9px 14px',
+          pointerEvents: 'auto',
+        }}
+      >
+        <span
+          aria-hidden
+          style={{
+            background: '#e5a000',
+            borderRadius: '50%',
+            flex: 'none',
+            height: '7px',
+            width: '7px',
+          }}
+        />
+        <span style={{ minWidth: 0 }}>{label}</span>
+        <a
+          href={exitPath}
+          onClick={exitHere}
+          style={{
+            color: '#ffffff',
+            flex: 'none',
+            fontWeight: 600,
+            textDecoration: 'underline',
+            textUnderlineOffset: '3px',
+            whiteSpace: 'nowrap',
+          }}
+        >
+          Exit preview
+        </a>
+      </div>
+    </div>
+  )
+}