@unitninety/site-kit 0.0.0-stage → 1.6.1

package/src/legacy/image.ts

@@ -0,0 +1,433 @@
+import type { EditorBlock, EditorField } from './contract'
+
+export type MediaId = number | string
+export type ImageFocalPoint = { x: number; y: number }
+export type ImageCrop = ImageFocalPoint & { width: number; height: number }
+export type ImageConstraints = {
+  mimeTypes?: string[]
+  maxBytes?: number
+  minWidth?: number
+  minHeight?: number
+  cropAspectRatios?: number[]
+}
+export type ImageVariantDeclaration = { media: string; constraints?: ImageConstraints }
+export type ImageVariant = {
+  asset: MediaId
+  crop: ImageCrop | null
+  focalPoint: ImageFocalPoint | null
+}
+export type ImageValue =
+  | null
+  | (ImageVariant & {
+      alt: string
+      decorative: boolean
+      caption: string | null
+      variants: Record<string, ImageVariant>
+    })
+export type ImageSeedVariant = {
+  asset: MediaId | { source: string }
+  crop?: ImageCrop | null
+  focalPoint?: ImageFocalPoint | null
+}
+export type ImageSeedValue =
+  | null
+  | (ImageSeedVariant & {
+      alt?: string
+      decorative?: boolean
+      caption?: string | null
+      variants?: Record<string, ImageSeedVariant>
+    })
+export type ImageAsset = {
+  id: MediaId
+  url: string
+  mimeType: string
+  width: number | null
+  height: number | null
+  filename: string
+  blurDataURL?: string
+}
+export type ImageRendition = {
+  url: string
+  width: number | null
+  height: number | null
+  blurDataURL?: string
+}
+export type ImageReadVariant = {
+  asset: ImageAsset | null
+  crop: ImageCrop | null
+  focalPoint: ImageFocalPoint | null
+  rendition: ImageRendition | null
+  status: 'ready' | 'missing' | 'processing' | 'error'
+}
+export type ImageReadValue =
+  | null
+  | (ImageReadVariant & {
+      alt: string
+      decorative: boolean
+      caption: string | null
+      variants: Record<string, ImageReadVariant>
+    })
+export type ImageValidationIssue = { path: string; message: string }
+export type ImageValidationOptions = {
+  path?: string
+  mode: 'draft' | 'publish'
+  required?: boolean
+  variants?: Record<string, ImageVariantDeclaration>
+}
+const record = (v: unknown): v is Record<string, unknown> =>
+  !!v && typeof v === 'object' && !Array.isArray(v)
+const at = (path: string, key: string) => (path ? `${path}.${key}` : key)
+const finite = (n: unknown): n is number => typeof n === 'number' && Number.isFinite(n)
+const id = (v: unknown) =>
+  (finite(v) && v > 0 && Number.isInteger(v)) || (typeof v === 'string' && v.trim().length > 0)
+const cropValid = (c: unknown): c is ImageCrop =>
+  record(c) &&
+  [c.x, c.y, c.width, c.height].every(finite) &&
+  (c.x as number) >= 0 &&
+  (c.y as number) >= 0 &&
+  (c.width as number) > 0 &&
+  (c.height as number) > 0 &&
+  (c.x as number) + (c.width as number) <= 100 &&
+  (c.y as number) + (c.height as number) <= 100
+
+/** Pure shape validation. Asset authorization and rendition readiness are enforced by the server. */
+export function validateImageValue(
+  value: unknown,
+  options: ImageValidationOptions,
+): ImageValidationIssue[] {
+  const issues: ImageValidationIssue[] = []
+  const path = options.path ?? ''
+  const issue = (p: string, message: string) => issues.push({ path: p, message })
+  if (value === null || value === undefined) {
+    if (options.required && options.mode === 'publish')
+      issue(path, 'An image is required for publication.')
+    return issues
+  }
+  if (!record(value)) return [{ path, message: 'Expected an Image object or null.' }]
+  function structural(v: Record<string, unknown>, p: string) {
+    for (const [key, allowed] of [
+      ['crop', ['x', 'y', 'width', 'height']],
+      ['focalPoint', ['x', 'y']],
+    ] as const) {
+      const geometry = v[key]
+      if (record(geometry))
+        for (const property of Object.keys(geometry)) {
+          if (!(allowed as readonly string[]).includes(property))
+            issue(at(at(p, key), property), 'Unknown image geometry property.')
+        }
+    }
+
+    if (!id(v.asset))
+      issue(
+        at(p, 'asset'),
+        'Expected a media ID; expanded assets and seed sources are not write values.',
+      )
+    if (v.crop !== null && !cropValid(v.crop))
+      issue(at(p, 'crop'), 'Crop must be a finite positive rectangle inside the original image.')
+    const point = v.focalPoint
+    if (point !== null) {
+      if (
+        !record(point) ||
+        !finite(point.x) ||
+        !finite(point.y) ||
+        point.x < 0 ||
+        point.x > 100 ||
+        point.y < 0 ||
+        point.y > 100
+      )
+        issue(at(p, 'focalPoint'), 'Focal point needs x and y between 0 and 100.')
+      else if (
+        cropValid(v.crop) &&
+        (point.x < v.crop.x ||
+          point.x > v.crop.x + v.crop.width ||
+          point.y < v.crop.y ||
+          point.y > v.crop.y + v.crop.height)
+      )
+        issue(at(p, 'focalPoint'), 'Focal point must lie inside the crop.')
+    }
+  }
+  structural(value, path)
+  if (typeof value.alt !== 'string') issue(at(path, 'alt'), 'Alternative text must be a string.')
+  if (typeof value.decorative !== 'boolean')
+    issue(at(path, 'decorative'), 'Decorative must be a boolean.')
+  if (value.caption !== null && typeof value.caption !== 'string')
+    issue(at(path, 'caption'), 'Caption must be text or null.')
+  if (value.decorative === true && value.alt !== '')
+    issue(at(path, 'alt'), 'Decorative images must have empty alternative text.')
+  if (
+    options.mode === 'publish' &&
+    value.decorative === false &&
+    typeof value.alt === 'string' &&
+    !value.alt.trim()
+  )
+    issue(at(path, 'alt'), 'Meaningful images need alternative text for publication.')
+  for (const key of Object.keys(value))
+    if (!['asset', 'alt', 'decorative', 'caption', 'focalPoint', 'crop', 'variants'].includes(key))
+      issue(at(path, key), 'Unknown Image property.')
+  if (value.variants !== undefined) {
+    if (!record(value.variants)) issue(at(path, 'variants'), 'Variants must be an object.')
+    else
+      for (const [key, v] of Object.entries(value.variants)) {
+        const p = at(at(path, 'variants'), key)
+        if (
+          !/^[a-zA-Z][a-zA-Z0-9_]*$/.test(key) ||
+          ['constructor', 'prototype', '__proto__'].includes(key) ||
+          !Object.hasOwn(options.variants ?? {}, key)
+        )
+          issue(p, 'Variant is not declared by this field.')
+        if (!record(v)) {
+          issue(p, 'An override must be a complete structural image value.')
+          continue
+        }
+        structural(v, p)
+        for (const prop of Object.keys(v))
+          if (!['asset', 'crop', 'focalPoint'].includes(prop))
+            issue(at(p, prop), 'Variants only override asset, crop and focal point.')
+      }
+  }
+  return issues
+}
+
+export class ImageValidationError extends Error {
+  constructor(public issues: ImageValidationIssue[]) {
+    super(issues.map((i) => `${i.path}: ${i.message}`).join('; '))
+    this.name = 'ImageValidationError'
+  }
+}
+/** Defaults are applied to absent properties only. Explicit invalid values never become defaults. */
+export function normalizeImageSeed(value: unknown): ImageSeedValue {
+  if (value === null || value === undefined) return null
+  if (!record(value))
+    throw new ImageValidationError([
+      { path: '', message: 'Expected an Image seed object or null.' },
+    ])
+  const structural = (v: Record<string, unknown>) => ({
+    ...v,
+    focalPoint: v.focalPoint === undefined ? null : v.focalPoint,
+    crop: v.crop === undefined ? null : v.crop,
+  })
+  const normalized = {
+    ...structural(value),
+    alt: value.alt === undefined ? '' : value.alt,
+    decorative: value.decorative === undefined ? false : value.decorative,
+    caption: value.caption === undefined || value.caption === '' ? null : value.caption,
+    variants: value.variants === undefined ? {} : value.variants,
+  }
+  if (record(normalized.variants))
+    normalized.variants = Object.fromEntries(
+      Object.entries(normalized.variants).map(([k, v]) => [k, record(v) ? structural(v) : v]),
+    )
+  const check = structuredClone(normalized) as Record<string, unknown>
+  const seedIssues: ImageValidationIssue[] = []
+  const translate = (v: Record<string, unknown>, path: string) => {
+    if (!record(v.asset)) return
+    if (
+      typeof v.asset.source === 'string' &&
+      v.asset.source.trim() &&
+      Object.keys(v.asset).length === 1
+    )
+      v.asset = v.asset.source
+    else
+      seedIssues.push({
+        path: at(path, 'asset'),
+        message: 'Seed asset must be a media ID or { source: nonempty string }.',
+      })
+  }
+  translate(check, '')
+  if (record(check.variants))
+    for (const [k, v] of Object.entries(check.variants))
+      if (record(v)) translate(v, `variants.${k}`)
+  const variants = record(check.variants)
+    ? Object.fromEntries(Object.keys(check.variants).map((k) => [k, { media: 'seed' }]))
+    : {}
+  const issues = [...seedIssues, ...validateImageValue(check, { mode: 'draft', variants })]
+  if (issues.length) throw new ImageValidationError(issues)
+  return normalized as ImageSeedValue
+}
+
+/** The existing upload importer uses source strings at upload positions. */
+export function imageSeedForImport(value: unknown): ImageSeedValue {
+  const normalized = normalizeImageSeed(value)
+  if (!normalized) return null
+  const lower = (v: ImageSeedVariant) => ({
+    ...v,
+    asset: typeof v.asset === 'object' ? v.asset.source : v.asset,
+  })
+  return {
+    ...lower(normalized),
+    variants: Object.fromEntries(
+      Object.entries(normalized.variants ?? {}).map(([k, v]) => [k, lower(v)]),
+    ),
+  }
+}
+
+export function validateImageDeclaration(
+  value: { constraints?: unknown; variants?: unknown },
+  path = '',
+): ImageValidationIssue[] {
+  const issues: ImageValidationIssue[] = []
+  function constraints(v: unknown, p: string) {
+    if (v === undefined) return
+    if (!record(v)) {
+      issues.push({ path: p, message: 'Constraints must be an object.' })
+      return
+    }
+    for (const [key, n] of Object.entries(v)) {
+      const issue = () => issues.push({ path: at(p, key), message: 'Invalid image constraint.' })
+      if (['maxBytes', 'minWidth', 'minHeight'].includes(key)) {
+        if (!finite(n) || n <= 0 || !Number.isInteger(n)) issue()
+      } else if (key === 'mimeTypes') {
+        if (
+          !Array.isArray(n) ||
+          !n.length ||
+          !n.every((s) => typeof s === 'string' && /^image\/[a-z0-9.+-]+$/i.test(s))
+        )
+          issue()
+      } else if (key === 'cropAspectRatios') {
+        if (!Array.isArray(n) || !n.length || !n.every((r) => finite(r) && r > 0)) issue()
+      } else issue()
+    }
+  }
+  constraints(value.constraints, at(path, 'constraints'))
+  if (value.variants !== undefined) {
+    if (!record(value.variants))
+      issues.push({ path: at(path, 'variants'), message: 'Variants must be a named object.' })
+    else
+      for (const [key, v] of Object.entries(value.variants)) {
+        const p = at(at(path, 'variants'), key)
+        if (
+          !/^[a-zA-Z][a-zA-Z0-9_]*$/.test(key) ||
+          ['constructor', 'prototype', '__proto__'].includes(key) ||
+          !record(v) ||
+          typeof v.media !== 'string' ||
+          !v.media.trim()
+        ) {
+          issues.push({ path: p, message: 'Variant needs a safe name and media condition.' })
+          continue
+        }
+        for (const prop of Object.keys(v))
+          if (!['media', 'constraints'].includes(prop))
+            issues.push({ path: at(p, prop), message: 'Unknown variant declaration property.' })
+        constraints(v.constraints, at(p, 'constraints'))
+      }
+  }
+  return issues
+}
+
+export type ImageAssetMetadata = {
+  mimeType?: string | null
+  filesize?: number | null
+  byteSize?: number | null
+  width?: number | null
+  height?: number | null
+}
+export function validateImageConstraints(
+  asset: ImageAssetMetadata,
+  crop: ImageCrop | null,
+  constraints: ImageConstraints = {},
+  path = '',
+): ImageValidationIssue[] {
+  const issues: ImageValidationIssue[] = []
+  const issue = (key: string, message: string) =>
+    issues.push({ path: at(at(path, 'constraints'), key), message })
+  if (constraints.mimeTypes && !constraints.mimeTypes.includes(asset.mimeType ?? ''))
+    issue('mimeTypes', 'Source image format is not allowed.')
+  const bytes = asset.byteSize ?? asset.filesize
+  if (constraints.maxBytes && (!finite(bytes) || bytes > constraints.maxBytes))
+    issue('maxBytes', 'Original image exceeds the byte limit or its size is unknown.')
+  if (crop !== null && !cropValid(crop))
+    return [...issues, { path: at(path, 'crop'), message: 'Invalid crop.' }]
+  const width = finite(asset.width) && asset.width > 0 ? asset.width : null
+  const height = finite(asset.height) && asset.height > 0 ? asset.height : null
+  const w =
+    width === null
+      ? null
+      : crop
+        ? Math.ceil(((crop.x + crop.width) * width) / 100) - Math.floor((crop.x * width) / 100)
+        : width
+  const h =
+    height === null
+      ? null
+      : crop
+        ? Math.ceil(((crop.y + crop.height) * height) / 100) - Math.floor((crop.y * height) / 100)
+        : height
+  if (constraints.minWidth && (w === null || w < constraints.minWidth))
+    issue('minWidth', 'Cropped image has too few usable horizontal pixels.')
+  if (constraints.minHeight && (h === null || h < constraints.minHeight))
+    issue('minHeight', 'Cropped image has too few usable vertical pixels.')
+  if (
+    constraints.cropAspectRatios &&
+    (w === null ||
+      h === null ||
+      !constraints.cropAspectRatios.some((r) => Math.abs(w - h * r) <= Math.max(1, r)))
+  )
+    issue('cropAspectRatios', 'Image aspect ratio does not match an allowed ratio.')
+  return issues
+}
+
+export function imagePosition(
+  image: { focalPoint: ImageFocalPoint | null; crop: ImageCrop | null } | null | undefined,
+  fallback = '50% 50%',
+): string {
+  const point = image?.focalPoint
+  if (!point || !finite(point.x) || !finite(point.y)) return fallback
+  const clamp = (v: number) => Math.min(100, Math.max(0, v))
+  const crop = image?.crop
+  if (crop)
+    return cropValid(crop)
+      ? `${clamp(((point.x - crop.x) / crop.width) * 100)}% ${clamp(((point.y - crop.y) / crop.height) * 100)}%`
+      : fallback
+  return `${clamp(point.x)}% ${clamp(point.y)}%`
+}
+
+export type ImageSlot = {
+  field: EditorField
+  path: string
+  get: () => unknown
+  set: (value: unknown) => void
+}
+/** Semantic boundaries for hydration and atomic writes, with the same block resolution as uploadSlots. */
+export function imageSlots(
+  content: unknown,
+  blocks: EditorBlock[],
+  allBlocks: EditorBlock[] = blocks,
+): ImageSlot[] {
+  const slots: ImageSlot[] = []
+  function fields(schema: EditorField[], container: unknown, path: string) {
+    if (!record(container)) return
+    for (const field of schema) {
+      const p = at(path, field.name),
+        value = container[field.name]
+      if (field.type === 'group' && field.element === 'image') {
+        slots.push({
+          field,
+          path: p,
+          get: () => container[field.name],
+          set: (v) => {
+            container[field.name] = v
+          },
+        })
+        continue
+      }
+      if (field.type === 'group') fields(field.fields ?? [], value, p)
+      if (field.type === 'array' && Array.isArray(value))
+        value.forEach((v, i) => fields(field.fields ?? [], v, at(p, String(i))))
+      if (field.type === 'blocks')
+        rows(
+          value,
+          field.blocks ??
+            (field.childBlocks ?? []).flatMap((slug) => allBlocks.filter((b) => b.slug === slug)),
+          p,
+        )
+    }
+  }
+  function rows(value: unknown, schema: EditorBlock[], path: string) {
+    if (!Array.isArray(value)) return
+    value.forEach((v, i) => {
+      const block = record(v) ? schema.find((b) => b.slug === v.blockType) : undefined
+      if (block) fields(block.fields, v, at(path, String(i)))
+    })
+  }
+  rows(content, blocks, '')
+  return slots
+}

package/src/legacy/index.ts

@@ -0,0 +1,209 @@
+/**
+ * @unitninety/site-kit — the client-site half of the platform contract.
+ *
+ * A `site-*` repo installs this instead of copy-pasting ~1,000 lines of plumbing. The
+ * split of entry points is deliberate:
+ *
+ *   @unitninety/site-kit          types, schema authoring, the fetcher, route factories
+ *   @unitninety/site-kit/bridge   the editing bridge — a client component
+ *   @unitninety/site-kit/draft    the "you are viewing a draft" bar — a client component
+ *   @unitninety/site-kit/shape    render helpers, safe in client components
+ *
+ * `bridge` and `shape` are separate because the fetcher holds the API key and must stay
+ * server-side. Importing them from one barrel is how a secret ends up in a browser
+ * bundle.
+ */
+
+export {
+  BRIDGE_VERSION,
+  type CollectionRoutes,
+  type EditorBlock,
+  type EditorField,
+  type EditorFieldType,
+  type ManifestCollection,
+  type PageDeclaration,
+  type PairedCredentials,
+  type SiteManifest,
+} from './contract'
+
+export { type NavEntry, pagesFromNav } from './nav'
+
+export {
+  array,
+  /*
+   * Exported under a different name for the reason `text` is: a site's own block library is
+   * conventionally `export const blocks = defineBlocks({…})`, and every site that declared a
+   * zone would otherwise shadow this import in the one file it needs it.
+   */
+  blocks as blocksField,
+  type BlockSpec,
+  checkbox,
+  code,
+  type CollectionSpec,
+  createManifest,
+  date,
+  defineBlocks,
+  defineCollections,
+  email,
+  group,
+  image,
+  video,
+  file,
+  type VideoOptions,
+  type FileOptions,
+  type ImageOptions,
+  layout,
+  type LayoutEntry,
+  type LayoutMeta,
+  link,
+  number,
+  reference,
+  relationship,
+  richText,
+  select,
+  sentence,
+  type SentenceValue,
+  SENTENCE_LINK,
+  singles,
+  type SingleSpec,
+  SLOT,
+  SLOT_BLOCK,
+  text as textField,
+  textarea,
+  upload,
+} from './defineBlocks'
+
+export {
+  block,
+  type BlockEntry,
+  collection,
+  type CollectionEntry,
+  type CollectionOptions,
+  defineSite,
+  form,
+  type FormDeclaration,
+  type FormEntry,
+  type FormFieldDeclaration,
+  type LayoutDeclaration,
+  manifestFrom,
+  type SingleDeclaration,
+  type Site,
+  type SiteSpec,
+} from './defineSite'
+
+export {
+  createContentClient,
+  type CollectionRow,
+  type ContentResult,
+  type OpeningHoursDay,
+  type OpeningHoursRow,
+  type PageSeo,
+  type Section,
+  type SeoMedia,
+  type SeoOrganisation,
+  type SiteSeo,
+  type SitemapEntry,
+} from './content'
+
+export {
+  createExitPreviewRoute,
+  createManifestRoute,
+  createPreviewRoute,
+  createRevalidateRoute,
+} from './routes'
+
+export {
+  applyTitleTemplate,
+  metadataFor,
+  organisationJsonLd,
+  robotsFrom,
+  sitemapFrom,
+  type SeoMetadata,
+} from './seo'
+
+export {
+  asMediaId,
+  collectMediaIds,
+  normaliseUploadsIn,
+  resolveUploadsIn,
+  uploadSlots,
+  type UploadSlot,
+} from './uploads'
+
+export {
+  doc,
+  FORMAT,
+  heading,
+  lineBreak,
+  link as richLink,
+  list,
+  listItem,
+  paragraph,
+  type RichBlock,
+  type RichInline,
+  type RichTextNode,
+  type RichTextValue,
+  text as richTextRun,
+} from './lexical'
+
+export { RichText } from './richText'
+
+export { type DomLike, toRichText } from './lexicalDom'
+
+export {
+  applyTranslationPatch,
+  ISO_COUNTRY_CODES,
+  languageFieldCandidate,
+  canonicalLocale,
+  deactivateLanguage,
+  duplicateWithFreshIdentities,
+  ensureStableIdentities,
+  evaluateLanguageHealth,
+  fallbackLocales,
+  isSemanticallyEmpty,
+  localizableFields,
+  localePath,
+  localePrefix,
+  reconcileStableIdentities,
+  RESERVED_LOCALE_PREFIXES,
+  resolveLocaleRequest,
+  resolveField,
+  sourceFingerprint,
+  stableAddressFor,
+  STABLE_ID_KEY,
+  selectLocale,
+  validateLanguageSettings,
+  type IdentityFactory,
+  type IdentityResult,
+  type LanguageDefinition,
+  type LanguageFieldHealth,
+  type LanguageHealth,
+  type LanguageLifecycleResult,
+  type LanguageSettings,
+  type LanguageSettingsValidation,
+  type LocalizableField,
+  type LocaleRequestResult,
+  type TranslationDocument,
+  type TranslationField,
+  type TranslationOwner,
+  type TranslationPatch,
+  type TranslationPatchResult,
+} from './languages'
+
+export {
+  createLanguageRuntime,
+  overlayLanguageOwner,
+  languagePreferenceCookie,
+  LANGUAGE_PREFERENCE_COOKIE,
+  LANGUAGE_VERSION,
+  type LanguageSnapshot,
+  type LanguageRuntimeOwner,
+} from './languages/runtime'
+export { languageLinks, languageHref, languageDirection } from './languages/links'
+export { languageMetadataFor, languageSitemapFrom } from './languages/seo'
+
+export { acceptsLanguageFrame, type LanguageFrameContext } from './preview'
+
+export * from './image'
+
+export * from './media'

package/src/legacy/language-switcher.tsx

@@ -0,0 +1,58 @@
+'use client'
+import React, { useEffect, useState } from 'react'
+import { languageLinks } from './languages/links'
+import { languagePreferenceCookie } from './languages/runtime'
+import type { LanguageDefinition } from './languages/types'
+// Called only by deliberate click/auxclick handlers; normal native navigation is preserved.
+const remember = (language: string) => {
+  document.cookie = languagePreferenceCookie(language, window.location.protocol === 'https:')
+}
+/** Unstyled links for the site's shared header or footer. */
+export function LanguageSwitcher({
+  languages,
+  locale,
+  logicalPath,
+  label = 'Language',
+  className,
+}: {
+  languages: readonly LanguageDefinition[]
+  locale: string
+  logicalPath: string
+  label?: string
+  className?: string
+}) {
+  const [suffix, setSuffix] = useState({ search: '', hash: '' })
+  useEffect(() => {
+    const update = () => setSuffix({ search: window.location.search, hash: window.location.hash })
+    update()
+    window.addEventListener('popstate', update)
+    window.addEventListener('hashchange', update)
+    return () => {
+      window.removeEventListener('popstate', update)
+      window.removeEventListener('hashchange', update)
+    }
+  }, [logicalPath])
+  const target = new URL(logicalPath, 'https://language.invalid')
+  if (!target.search) target.search = suffix.search
+  if (!target.hash) target.hash = suffix.hash
+  const currentPath = target.pathname + target.search + target.hash
+  return (
+    <nav aria-label={label} className={className}>
+      {languageLinks({ languages, locale, logicalPath: currentPath }).map((link) => (
+        <a
+          key={link.locale}
+          href={link.href}
+          hrefLang={link.locale}
+          lang={link.locale}
+          aria-current={link.current ? 'page' : undefined}
+          onClick={() => remember(link.locale)}
+          onAuxClick={(event) => {
+            if (event.button === 1) remember(link.locale)
+          }}
+        >
+          {link.label}
+        </a>
+      ))}
+    </nav>
+  )
+}