@styleflow.app/flowpress-astro-core 1.0.0-beta.1 → 1.0.0-beta.10

package/CHANGELOG.md

@@ -2,12 +2,91 @@
 
 ## Unreleased
 
+## 1.0.0-beta.10
+
+- Added a versioned catalog of official default block adapters and a public
+  source generator for editable project overrides.
+- Let an official default render a block without recursively selecting the
+  override currently wrapping it, while preserving certified overrides for
+  every nested child.
+- Added reusable `FLOWPRESS_MEDIA` resolution, Astro image remote patterns and
+  safe upload/media proxy helpers with `GET`, `HEAD`, range and cache support.
+- Extended normalized block HTML props with an explicit safe attribute
+  allowlist; Gutenberg event handlers, inline styles and Styleflow-owned data
+  attributes remain blocked.
+
+## 1.0.0-beta.9
+
+- Validated typography variants against the union of contract variants when
+  the block adapter has not yet supplied its typography type, preventing the
+  composition registry from rejecting valid heading-only variants early.
+
+## 1.0.0-beta.8
+
+- Normalized finite numeric CMS values for enumerated Styleflow axes to their
+  canonical contract strings, so typography variants such as WordPress `v=0`
+  remain valid in strict production builds without emitting a fallback.
+
+## 1.0.0-beta.7
+
+- Fixed theme-aware logo selection by placing fallback visibility variables on
+  the document root, allowing the nearest global or nested Styleflow theme to
+  override them while preserving per-block logo overrides.
+
+## 1.0.0-beta.6
+
+- Added required `htmlProps`, `styleflowProps`, composition and deterministic
+  render context to every certified block adapter.
+- Added single-emission composition stylesheets for validated WordPress block
+  CSS, plus theme-aware positive/negative Site Logo rendering.
+- Added the no-hydration multi-theme runtime and `sf/theme-toggle` adapter.
+- Made `<S.*>` the only public Astro authoring syntax in package sources.
+- Added `FlowpressCompositionV1`, typed `resolvedData`,
+  `FlowpressClient.getComposition()` and recursive production fail-closed
+  rendering with exact compatibility commands in development.
+
+## 1.0.0-beta.5
+
+- Updated the exact `@styleflow.app/astro` dependency to `1.0.0-beta.4`,
+  adopting the Styleflow contract beta.6 validator and generated runtime.
+- Kept the grouped CMS coordinates and Gutenberg block format unchanged; no
+  legacy adapter was introduced.
+
+## 1.0.0-beta.4
+
+- Exported the `FlowpressLinkValue` relational contract and centralized safe
+  href extraction for resolved internal, external, protocol, and fragment
+  destinations.
+- Made failed, missing, and bare-`#` relations fail closed: buttons retain
+  their label and Styleflow semantics as non-interactive elements, while
+  cards and list fallbacks emit anchors only for a valid resolved href.
+- Added renderer and unit fixtures for missing translations, root-relative
+  query/fragment paths, safe protocols, and invalid schemes.
+
+## 1.0.0-beta.3
+
+- Deferred generic Gutenberg semantic validation until its renderer branch is
+  selected, preventing valid numeric heading variants from being validated as
+  body typography and spuriously falling back to `md`.
+- Added a strict production fixture for `core/heading` with `v="5"` and verified
+  that the emitted Styleflow type and variant remain `heading` and `5`.
+
+## 1.0.0-beta.2
+
+- Added exact `@splidejs/splide@4.1.4` support and dedicated renderers for
+  `sf/carousel` and `sf/carousel-item` with responsive item counts, arrows,
+  pagination, drag, focused keyboard control, loop and autoplay.
+- Added accessible live-region integration and mandatory Play/Pause controls
+  for autoplay, including hover/focus pauses and reduced-motion protection.
+- Added defensive CMS clamps, per-instance custom-element lifecycle cleanup,
+  readable no-JavaScript layouts and a diagnostic static fallback that keeps
+  legacy content whose direct children are not carousel items.
+
 ## 1.0.0-beta.1
 
 - Updated the exact `@styleflow.app/astro` dependency to `1.0.0-beta.1`,
   keeping consumer trees on one runtime while adopting deterministic CLI
   reports. Runtime behavior is unchanged.
-
 ## 1.0.0-beta.0
 
 - Adopted the grouped Styleflow vNext project contract and the exact Astro v1

package/README.md

@@ -9,8 +9,8 @@ The package must not import from an application or project plugin.
 ## Install
 
 ```bash
-pnpm add @styleflow.app/flowpress-astro-core@1.0.0-beta.1 \
-  @styleflow.app/astro@1.0.0-beta.1
+pnpm add @styleflow.app/flowpress-astro-core@1.0.0-beta.10 \
+  @styleflow.app/astro@1.0.0-beta.6
 ```
 
 Prereleases are pinned exactly. The package expects Astro 7 or newer and the
@@ -54,6 +54,85 @@ visible characters. The exported
 from rendered CMS blocks so consumers can generate Tailwind
 `@source inline()` directives before compiling their frontend CSS.
 
+The package exports `FlowpressLinkValue`, `flowpressLinkValue()` and
+`flowpressLinkHref()` for the WordPress relational link contract. Navigation
+paths are root-relative and are rendered only when resolution succeeds.
+`missing_translation`, `missing_entity`, invalid schemes, and a bare `#` fail
+closed. FlowPress buttons keep their authored label and semantic styling as an
+`aria-disabled` non-interactive element; cards and list fallbacks omit the
+anchor. Canonical, hreflang, social and media URLs remain under their separate
+absolute-URL contracts.
+
+`sf/carousel` renders an accessible horizontal Splide carousel whose direct
+children must be `sf/carousel-item`; each item can recursively contain any
+renderable block. Item counts inherit across `base/sm/md/lg/xl/2xl`, with
+defaults `1/1/2/3/3/3`. Arrows, pagination, drag/swipe, focused keyboard
+navigation, loop and autoplay follow CMS attributes. Autoplay always includes
+one Play/Pause control, pauses on configured hover/focus states and starts
+paused under reduced-motion preferences. Every custom element owns and
+destroys exactly one Splide instance.
+
+Stored CMS values are clamped to the public contract: item counts and movement
+`1–12`, gap `0–128px`, autoplay interval `1000–60000ms`, and transition speed
+`0–5000ms`. Without JavaScript, all valid items remain a readable responsive
+grid and dead controls are hidden. If a legacy carousel contains any direct
+child other than `sf/carousel-item`, no interactive instance is initialized:
+the complete content renders statically, with a development diagnostic.
+
+## Site Editor composition
+
+`FlowpressClient.getComposition(uri, locale)` reads the public
+`FlowpressCompositionV1` contract. `CompositionRenderer.astro` walks its block
+tree through an explicit `FlowpressBlockAdapters` registry, passes authored
+attributes and `resolvedData` separately, and never renders `innerHtml` as a
+fallback. Blocking WordPress diagnostics always fail the render. Missing or
+draft adapters, absent block-type descriptors and schema-fingerprint drift
+are visible diagnostics in development and fail closed in production with
+the exact scaffold, refresh or approval command. The fingerprint comparison
+is repeated by Astro and does not rely only on the CMS gate.
+Before invoking an adapter, the renderer resolves the universal Styleflow
+attributes through the same framework-neutral validator used by the built-in
+renderer and passes them as `styleflowProps`. Project adapters can therefore
+apply the authored semantic context to their real root without accepting raw
+WordPress visual values.
+
+Every adapter also receives required normalized `htmlProps` (`anchor` → `id`
+and the additional classes), the full composition and a deterministic render
+context. The public HTML allowlist also preserves `title`, `role`, `lang`,
+`dir`, `tabindex`, `aria-*` and project `data-*` attributes. Inline styles,
+event handlers and Styleflow-owned `data-*` attributes are never copied from
+Gutenberg indiscriminately. WordPress-processed block custom CSS is emitted
+once at the root.
+`ThemeRuntime.astro` applies the persisted contract theme before paint and
+progressively enhances `sf/theme-toggle` without hydrating React. The shared
+Site Logo adapter renders positive and negative variants while inherited CSS
+variables make the nearest nested theme authoritative.
+
+```astro
+---
+import CompositionRenderer from "@styleflow.app/flowpress-astro-core/CompositionRenderer.astro";
+import { blockAdapters } from "./generated/block-adapter-registry";
+---
+
+<CompositionRenderer composition={composition} adapters={blockAdapters} />
+```
+
+The package publishes a versioned `flowpressDefaultBlockCatalog` and
+`DefaultBlockAdapter.astro`. A project registry can therefore resolve a block
+in this order: conventional local `namespace-block.astro`, explicit manifest
+renderer, official default. Calling the official default skips only the
+current override and keeps the same registry for nested children, avoiding
+recursion without losing child overrides. File discovery never changes a
+`draft`, missing or stale fingerprint into a certified adapter.
+
+`createFlowpressDefaultBlockAdapterSource(blockName)` returns the editable
+source used by scaffolding when `--from-default` is selected. Unsupported
+blocks throw instead of pretending that a semantic implementation exists.
+
+Static adapters produce no JavaScript by default. A project opts into client
+runtime only inside adapters classified as interactive; React views rendered
+without `client:*` remain server-only HTML.
+
 Heading, rich-text, quote and matching core blocks accept Gutenberg alignment
 from either `style.typography.textAlign` or the FlowPress `textAlign` field.
 Only `left`, `center`, `right`, `justify`, `start` and `end` reach CSS.
@@ -122,6 +201,18 @@ assistive technology and without JavaScript; `prefers-reduced-motion: reduce`
 skips the animation entirely. Browsers without viewport observation keep the
 server-rendered final value instead of guessing when to start.
 
+## Media
+
+`resolveFlowpressMediaUrl()` reads `FLOWPRESS_MEDIA`, falling back to
+`BACKEND_URL`, while `flowpressMediaRemotePattern()` returns the matching Astro
+image pattern. URLs with credentials, query strings or fragments are rejected.
+
+`proxyFlowpressUpload()` and `proxyFlowpressMedia()` are shared request
+handlers for server output and static Pages Functions. They accept only
+`GET`/`HEAD`, preserve conditional and Range requests plus cache metadata, and
+use explicit request/response header allowlists so cookies, authorization and
+other sensitive headers never cross the proxy boundary.
+
 ## Release
 
 ```bash
@@ -142,7 +233,7 @@ The TypeScript template-hierarchy suite is self-contained. Its additional PHP
 parity test runs when the sibling `flowpress-wordpress-core` checkout is
 available locally and is skipped in a standalone package checkout.
 
-Publish v1 betas on `next` only after Components and WordPress Core are
+Publish `1.0.0-beta.10` on `next` only after the exact Styleflow prerelease is
 available. Inspect `npm view`, `gitHead`, integrity and the downloaded tarball.
 Promote to `latest` only after the DMO canary and rollback gate.
 

package/dist/astro/BaseLayout.astro

@@ -1,19 +1,22 @@
 ---
 import type { SfSeo } from "../types.js";
 import S from "@styleflow.app/astro/S.astro";
+import ThemeRuntime from "./ThemeRuntime.astro";
 
 interface Props {
   lang?: string;
   seo?: SfSeo | null;
   siteName?: string;
   theme?: string;
+  themes?: string[];
 }
 
 const {
   lang = "it",
   seo = null,
   siteName = import.meta.env.PROJECT_NAME ?? "FlowPress",
-  theme
+  theme,
+  themes = theme ? [theme] : []
 } = Astro.props;
 const title = seo?.title || siteName;
 const description = seo?.description || "";
@@ -26,6 +29,7 @@ const jsonLd = seo?.jsonLd ? JSON.stringify(seo.jsonLd) : null;
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width" />
+    {theme && themes.length ? <ThemeRuntime themes={themes} defaultTheme={theme} /> : null}
     <title>{title}</title>
     {description && <meta name="description" content={description} />}
     {robots && <meta name="robots" content={robots} />}

package/dist/astro/CompositionRenderer.astro

@@ -0,0 +1,127 @@
+---
+import type { FlowpressBlockAdapters } from "../block-renderers.js";
+import {
+  flowpressAdapterCompatibilityIssue,
+  flowpressBlockHtmlProps,
+  flowpressCompositionLogoStyles,
+  flowpressBlockTypeDescriptors
+} from "../composition.js";
+import {
+  resolveFlowpressBlockStyleflowProps,
+  type StyleflowContract
+} from "../styleflow.js";
+import type { FlowpressBlock, FlowpressCompositionV1 } from "../types.js";
+
+interface Props {
+  composition: FlowpressCompositionV1;
+  adapters: FlowpressBlockAdapters;
+  blocks?: FlowpressBlock[];
+  contract?: StyleflowContract;
+  parentBlockName?: string;
+  production?: boolean;
+  depth?: number;
+}
+
+const {
+  composition,
+  adapters,
+  blocks = composition.blocks,
+  contract,
+  parentBlockName,
+  production = import.meta.env.PROD,
+  depth = 0
+} = Astro.props;
+
+const blocking = composition.diagnostics.filter((diagnostic) => diagnostic.blocking);
+if (blocking.length > 0 && production) {
+  throw new Error(
+    `FlowPress composition ${composition.sourceDigest} is not renderable:\n`
+      + blocking.map(({ code, message }) => `- ${code}: ${message}`).join("\n")
+  );
+}
+const descriptors = flowpressBlockTypeDescriptors(composition);
+const logoStyles = parentBlockName === undefined
+  ? flowpressCompositionLogoStyles(composition)
+  : "";
+---
+
+{parentBlockName === undefined && composition.stylesheets.map((stylesheet) => (
+  <style data-flowpress-composition-style={stylesheet.id} set:html={stylesheet.css} />
+))}
+{logoStyles ? <style data-flowpress-logo-styles set:html={logoStyles} /> : null}
+
+{blocking.length > 0 && !production && parentBlockName === undefined ? (
+  <aside data-flowpress-composition-diagnostics role="status">
+    <strong>FlowPress composition diagnostics</strong>
+    <ul>
+      {blocking.map(({ code, message, command }) => (
+        <li data-diagnostic-code={code}>
+          {message}
+          {command ? <code>{command}</code> : null}
+        </li>
+      ))}
+    </ul>
+  </aside>
+) : null}
+
+{blocks.map((block) => {
+  const adapter = adapters[block.name];
+  const issue = flowpressAdapterCompatibilityIssue(block.name, descriptors, adapters);
+  if (issue && production) throw new Error(issue.message);
+  if (!adapter) {
+    return (
+      <aside data-flowpress-compatibility={issue?.code ?? "missing-adapter"} data-block-name={block.name} role="status">
+        <strong>Missing block adapter: {block.name}</strong>
+        <code>{issue?.command}</code>
+      </aside>
+    );
+  }
+  const Adapter = adapter.renderer;
+  const children = block.innerBlocks ?? [];
+  const styleflowProps = resolveFlowpressBlockStyleflowProps(
+    block.attributes,
+    contract,
+    {},
+    {
+      strict: production,
+      onDiagnostic: (diagnostic) => console.warn(
+        `[${diagnostic.code}] ${diagnostic.message}`
+      )
+    }
+  );
+  const htmlProps = flowpressBlockHtmlProps(block.attributes);
+  return (
+    <>
+      {issue && (
+        <aside data-flowpress-compatibility={issue.code} data-block-name={block.name} role="status">
+          <strong>{issue.message}</strong>
+          <code>{issue.command}</code>
+        </aside>
+      )}
+      <Adapter
+        block={block}
+        parentBlockName={parentBlockName}
+        contract={contract}
+        composition={composition}
+        styleflowProps={styleflowProps}
+        htmlProps={htmlProps}
+        context={{
+          ...(parentBlockName ? { parentBlockName } : {}),
+          depth,
+          production
+        }}
+        adapters={adapters}
+      >
+        <Astro.self
+          composition={composition}
+          adapters={adapters}
+          blocks={children}
+          contract={contract}
+          parentBlockName={block.name}
+          production={production}
+          depth={depth + 1}
+        />
+      </Adapter>
+    </>
+  );
+})}

package/dist/astro/DefaultBlockAdapter.astro

@@ -0,0 +1,35 @@
+---
+import type {
+  FlowpressBlockRendererProps,
+  FlowpressBlockRenderers
+} from "../block-renderers.js";
+import GutenbergRenderer from "./GutenbergRenderer.astro";
+
+const {
+  block,
+  contract,
+  styleflowProps,
+  htmlProps,
+  composition,
+  adapters,
+  context
+} = Astro.props as FlowpressBlockRendererProps;
+const blockRenderers = Object.fromEntries(
+  Object.entries(adapters).map(([name, definition]) => [name, definition.renderer])
+) as FlowpressBlockRenderers;
+---
+
+<GutenbergRenderer
+  blocks={[block]}
+  contract={contract}
+  blockRenderers={blockRenderers}
+  adapterDefinitions={adapters}
+  composition={composition}
+  rootHtmlProps={htmlProps}
+  rootStyleflowProps={styleflowProps}
+  parentBlockName={context.parentBlockName}
+  production={context.production}
+  depth={context.depth}
+  skipCustomRendererFor={block.name}
+  requireRegisteredAdapters
+/>

package/dist/astro/DefaultTemplate.astro

@@ -11,7 +11,12 @@ const hasGutembergBlocks = Array.isArray(content?.contentBlocks) && content.cont
 //TODO SET GLOBAL LOCAL ON ENV
 ---
 
-<BaseLayout lang={route.locale || "it"} seo={route.seo} theme={styleflowContract?.defaultTheme}>
+<BaseLayout
+  lang={route.locale || "it"}
+  seo={route.seo}
+  theme={styleflowContract?.defaultTheme}
+  themes={styleflowContract?.semantic.themes}
+>
 
   {hasGutembergBlocks ? (
     <GutenbergRenderer