@storystick/next 0.0.0-stage → 0.2.0-rc.0

package/dist/video.js

@@ -0,0 +1 @@
+export { StorystickVideo, resolveVideo, } from '@storystick/react/video';

package/package.json

@@ -1,6 +1,131 @@
 {
   "name": "@storystick/next",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0-rc.0",
+  "license": "FSL-1.1-MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "react-server": "./dist/index.react-server.js",
+      "import": "./dist/index.js"
+    },
+    "./preview-text": {
+      "types": "./dist/preview-text.d.ts",
+      "import": "./dist/preview-text.js"
+    },
+    "./image": {
+      "types": "./dist/image.d.ts",
+      "import": "./dist/image.js"
+    },
+    "./file": {
+      "types": "./dist/file.d.ts",
+      "import": "./dist/file.js"
+    },
+    "./video": {
+      "types": "./dist/video.d.ts",
+      "import": "./dist/video.js",
+      "default": "./dist/video.js"
+    },
+    "./link": {
+      "types": "./dist/link.d.ts",
+      "import": "./dist/link.js"
+    },
+    "./query": {
+      "types": "./dist/query.d.ts",
+      "import": "./dist/query.js"
+    },
+    "./rich-text": {
+      "types": "./dist/rich-text.d.ts",
+      "import": "./dist/rich-text.js"
+    },
+    "./slice-zone": {
+      "types": "./dist/slice-zone.d.ts",
+      "import": "./dist/slice-zone.js"
+    },
+    "./revalidate": {
+      "types": "./dist/revalidate.d.ts",
+      "import": "./dist/revalidate.js"
+    },
+    "./preview-nav": {
+      "types": "./dist/preview-nav.d.ts",
+      "import": "./dist/preview-nav.js"
+    },
+    "./preview-nav-location": {
+      "types": "./dist/preview-nav-location.d.ts",
+      "import": "./dist/preview-nav-location.js"
+    },
+    "./preview": {
+      "types": "./dist/preview/index.d.ts",
+      "import": "./dist/preview/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    }
+  },
+  "files": [
+    "dist",
+    "recipes",
+    "LICENSE",
+    "README.md",
+    "PUBLIC-API.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": false,
+    "tag": "beta"
+  },
+  "peerDependencies": {
+    "next": "^15.5.28",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8"
+  },
+  "dependencies": {
+    "server-only": "^0.0.1",
+    "@storystick/media": "0.2.0-rc.0",
+    "@storystick/client": "0.2.0-rc.0",
+    "@storystick/types": "0.1.0-rc.0",
+    "@storystick/react": "0.2.0-rc.0",
+    "@storystick/preview": "0.2.0-rc.0"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^22.13.10",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.5",
+    "fast-check": "^4.7.0",
+    "jsdom": "^29.0.2",
+    "next": "15.5.28",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "typescript": "^5.8.2",
+    "vitest": "^3.1.1",
+    "sharp": "0.35.5"
+  },
+  "engines": {
+    "node": ">=24.19.0 <25"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/withstorystick/storystick.git",
+    "directory": "packages/next"
+  },
+  "homepage": "https://storystick.app",
+  "bugs": {
+    "url": "https://storystick.app"
+  },
+  "scripts": {
+    "build": "node ../../scripts/package-dist.mjs clean && tsc && node ../../scripts/package-dist.mjs seal",
+    "test": "vitest run",
+    "test:types": "tsc -p tsconfig.type-tests.json --noEmit",
+    "test:dist-fresh": "node ../../scripts/package-dist.mjs assert",
+    "test:watch": "vitest",
+    "test:recipes": "tsc -p tsconfig.recipes.json --noEmit"
+  }
 }

package/recipes/README.md

@@ -0,0 +1,91 @@
+# Published language routes and explicit resource mirrors
+
+These recipes use the generated query schema and the C4a publication selector.
+They do not implement a second translation selector in application code.
+
+## Prefix routing (one or several languages)
+
+```ts
+const site = createSite({ definition, siteUrl: 'https://example.com' })
+const route = await site.resolvePage(props)
+const languages = site.alternates(route)
+```
+
+The project owns enabled locales and prefix settings. Render the language switch
+from `languages`: EN `/resources/security` may correspond to FR
+`/fr/ressources/securite`. Do not replace a prefix on the current pathname.
+Unpublished or removed languages are absent. `site.params()`, `site.metadata()`
+and `site.sitemap()` use actual publications. Historical redirects remain
+server-owned, including translated parents and renamed segments.
+
+## One domain per language
+
+```ts
+const site = createSite({
+  definition,
+  siteUrl: 'https://example.fr',
+  domainLocale: 'fr',
+  publicOrigins: {
+    en: 'https://example.com',
+    fr: 'https://example.fr',
+  },
+})
+```
+
+Deploy the same definition with `domainLocale: 'en'` on the English origin.
+`domainLocale` explicitly binds an unprefixed pathname to a language; it does
+not change the project default or publication availability. Origins must be
+distinct HTTP(S) origins without paths, credentials, queries or fragments.
+Configure an origin for every enabled language. An incomplete domain map fails
+explicitly; it never points a missing language at the current host.
+
+The French deployment resolves `/ressources/securite` in FR. Its static params
+and sitemap contain French publications only; hreflang includes the real English
+URL. Compound links and rich-text marks use the selected destination publication
+and carry this plain configuration across JSON/RSC boundaries. `site.alternates`
+and `site.metadata` use the same address mapping. Historical redirects are
+mapped to the destination language's origin.
+
+No implicit Host lookup or unconditional Next dynamic API is added. For a custom
+multi-host router, select a configured deployment explicitly outside this helper;
+do not pass an unchecked Host header as an origin. Domain/DNS administration and
+the Studio Preview origin configuration are separate deployment work. Existing
+project pathname collision constraints still apply.
+
+## Opt-in resource mirror: French UI, English publication
+
+`resource-mirror.ts` is a compiled, tested customer recipe. Replace its synthetic
+`ResourceSchema` with the generated resource story for your site.
+
+1. Load the resource list through `resourceCollection(client, 'fr')`. The server
+   selects FR when published, otherwise its configured publication fallback,
+   once per identity **before** filtering, sorting or pagination. Use
+   `mirrorHref(row.resolvedPathname, 'fr', routing)` only on this opted-in mirror
+   surface. Ordinary document links keep linking to the actual publication.
+2. In the mirror page, call `resolveResourceMirror(client, site.resolvePage,
+   { uiLocale: 'fr', pathname })`, with the **canonical resource path** (strip
+   the application's language prefix using `resolveLocalePathname`, if used).
+   Handle null as not-found and the returned route's redirect/not-found outcome
+   with the normal Next handlers. Cache this loader per render when sharing it
+   between the page and `generateMetadata`.
+3. Render the returned `document`, preserving its link sidecars selected for FR
+   navigation. Set the interface container's `lang` to `uiLocale` and the resource
+   body's `lang` to `contentLocale`. An EN fallback body remains English.
+4. Call `site.metadata(result.route)` for the actual publication's canonical,
+   hreflang and robots. An EN fallback yields the EN canonical and no invented
+   FR alternate. The synthetic mirror is not added to `site.sitemap()`.
+5. Publish FR: the same collection now selects the FR publication instead of EN.
+   Its actual translated path and canonical replace the fallback entry. If the
+   new FR slug differs, the old synthetic mirror URL returns not-found; no
+   translation identity is inferred from a matching old slug. Add a deliberate
+   application redirect only if that is part of the site's URL policy.
+
+This recipe is for public reads. It rejects incomplete/non-public selection and
+ambiguous mirror paths. A service error propagates; it never permits switching
+to another language or exposing a draft. The metadata route read also verifies
+document, language and snapshot identity when available. The returned document
+is the selected Query V2 result, not a re-read of its body in a different locale.
+Use ordinary Preview routes for Studio editing.
+
+Run `pnpm --filter @storystick/next exec tsc -p tsconfig.recipes.json --noEmit`
+and the `resource-mirror.test.ts` tests to verify the recipe without a live site.

package/recipes/resource-mirror.ts

@@ -0,0 +1,49 @@
+import type { Client, QueryFieldType, QuerySchemaDefinition, QueryStoryType, ResolvedRoute } from '@storystick/client'
+import { publicHrefForLocale, type LocaleRoutingSettings } from '@storystick/client/locale-routing'
+
+/** Synthetic generated schema shape. Replace it with your generated resource story. */
+export type ResourceSchema = QuerySchemaDefinition<{
+  resource: QueryStoryType<{ title: string }, { title: QueryFieldType<string, 'is', true> }, false, false, true>
+}>
+
+export function resourceCollection(client: Client<ResourceSchema>, uiLocale: string) {
+  // The server chooses ONE publication per identity BEFORE filtering or paging.
+  return client.query('resource').selectAll().locale(uiLocale).publicationFallback('configured')
+}
+
+/** Opt-in mirror address. This is an app route, never an hreflang publication. */
+export function mirrorHref(pathname: string, uiLocale: string, routing: LocaleRoutingSettings): string {
+  return publicHrefForLocale(pathname, uiLocale, routing)
+}
+
+export async function resolveResourceMirror(
+  client: Client<ResourceSchema>,
+  resolvePublication: (input: { pathname: string; locale: string }) => Promise<ResolvedRoute>,
+  input: { pathname: string; uiLocale: string },
+) {
+  const result = await resourceCollection(client, input.uiLocale)
+    .where((_, { route }) => route.pathname.is(input.pathname))
+    .page({ first: 2 }).execute()
+  if (result.exactness !== 'exact' || result.meta.scope.kind !== 'activePublication') {
+    throw new Error('Resource mirrors require an exact public publication read.')
+  }
+  if (result.data.length === 0) return null
+  if (result.data.length !== 1) throw new Error('Several resource identities own this mirror path.')
+  const selected = result.data[0]!
+  const contentLocale = selected._locale?.code
+  if (!contentLocale || selected.resolvedPathname === undefined) throw new Error('Missing publication address.')
+
+  // Reuse the publication's own route facts and SEO; never forge a French route.
+  // A failure propagates. It does not authorize another language or a draft.
+  const route = await resolvePublication({ pathname: selected.resolvedPathname, locale: contentLocale })
+  if (route.type !== 'document') return { uiLocale: input.uiLocale, contentLocale, route }
+  if (route.document.documentId !== selected.documentId || route.localeContext.locale !== contentLocale ||
+      (route.document.snapshotId !== undefined && selected.snapshotId !== undefined && route.document.snapshotId !== selected.snapshotId)) {
+    throw new Error('The resource publication changed during route resolution.')
+  }
+  // Render the selection made for the UI locale: its C4b link sidecars retain
+  // French navigation even when the resource body is an English publication.
+  return { uiLocale: input.uiLocale, contentLocale, document: selected,
+    reason: contentLocale === input.uiLocale ? 'requested' as const : 'fallback' as const,
+    route }
+}