Extract reusable stackpress-leptos library and consume it from framework-view #17

Activity

1. cblanquera commented on Oct 27, 2026

   

   cblanquera

   on Oct 27, 2026

   MemberAuthor

   More actions

   Suggested implementation approach

   The direction is to extract the reusable library and make view the integration owner. The symbols and features below are design sketches, not existing compile-verified APIs.

   1. Inventory dependencies before moving files

   Classify every current UI module:

   • Components/layout/CSS, reactive state, generic language contexts, formatting, rich content and generic resource utilities are candidates for crates/leptos.
   • RouteCatalog/Root mount adapters, PageSnapshot/PageContract wrappers, asset/seed assembly and the Stackpress renderer trait implementations belong in view.
   • Split generic rendering execution from protocol-specific configuration/results only where the code actually needs that boundary.

   Search source and public signatures, including display helpers. Replacing only the manifest dependency would leave types such as PublicLocation and ViewError leaking into the reusable API.

   Keep one authority for shared safety rules. For example, locate a genuinely generic safe-href value/parser at the lower layer if both layers need it, then adapt Stackpress locations explicitly. Do not replace checked locations with arbitrary strings or copy subtly different validators into both crates.

   2. Let view own the adapter wrapper

   An illustrative synchronous adapter design:

   // In framework-view, behind a native Leptos SSR integration feature.
   use crate::{PageRenderer, PageSnapshot, RenderFuture};
   use stackpress_leptos::render::Renderer; // Proposed generic renderer.
   
   // The adapter is a local type, so it can implement view's renderer contract.
   pub struct LeptosPageRenderer<C> {
       renderer: Renderer,
       component: C,
       // Page contract/assets/limits remain owned by this integration.
   }

   Its PageRenderer<T> implementation should validate the existing page contract, adapt public page data into component input, call the generic renderer, then perform the existing seed/asset/HTML-limit processing in the proper order. Preserve current head evaluation, escaping and error precedence; do not assume these can be reordered safely.

   The reusable renderer should use its own generic errors/options and component output. It must not expose PageSnapshot, PageContract or ViewError.

   Audit async/streaming separately: preserve request-local Owner lifetime, Send boundaries, cancellation, bounded buffering, replay compatibility and opt-in defaults. Existing internal worker/runtime supervision is not permission to create an additional layer of detached rendering tasks.

   3. Use optional integration features without reverse edges

   Illustrative view manifest fragment:

   [features]
   default = []
   leptos-ssr = ["dep:stackpress-leptos", "stackpress-leptos/ssr", "server"]
   leptos-hydrate = ["dep:stackpress-leptos", "stackpress-leptos/hydrate"]
   leptos-csr = ["dep:stackpress-leptos", "stackpress-leptos/csr"]
   
   [dependencies.stackpress-leptos]
   path = "../../leptos"
   optional = true
   default-features = false

   Retain view's existing optional server definition and target gating. These proposed names require a feature matrix review. In the extracted library, ssr must no longer forward to framework-view/server. Its only Stackpress identity should be package ownership; it is a normal library, not a mandatory host plugin.

   Keep upstream leptos distinct from stackpress-leptos, and decide facade aliases explicitly. Map old root framework-ui-* features deliberately rather than silently changing which layer they select. Never use one all-features build to combine mutually exclusive render modes.

   4. Adapt preferences from view to generic reactive values

   Keep #15's persistence and host-policy work in view. Let the reusable library receive explicit initial values and callbacks.

   For example, the existing ThemeState concept can retain its generic behavior:

   // Proposed post-extraction imports, initialized inside a Leptos Owner.
   use stackpress_leptos::state::{Theme, ThemeState};
   
   let theme = ThemeState::new(Theme::Dark);
   // Apply an explicitly acknowledged value; this performs no persistence.
   theme.set(Theme::Light);

   A view adapter maps its persistent ThemePreference into this UI value. That mapping should be exhaustive, including System, and preserve before-paint/hydration agreement. It should not give stackpress-leptos access to cookie parsing, native file stores or view's Preferences type.

   Use the same direction for locale/dictionaries, flash-to-notification display and allowed-action hints. Actual authorization remains at the host operation boundary even when the view plugin is absent.

   5. Migrate consumers and prove independent use

   Update framework-admin plus all generated import/feature templates before regenerating owned output. Existing gallery/shared examples are not sufficient independence evidence if they still depend on view/language/application contracts.

   Create a small consumer outside the application graph, with its own selected build modes, depending on upstream Leptos and the new library only. Prove real component rendering/interaction, not just successful imports.

   Suggested checks:

   # Selected consumer graph: inspect normal edges for forbidden host/view dependencies.
   cargo tree --manifest-path /path/to/independent-consumer/Cargo.toml -e normal
   
   # Run native SSR tests and a separate client build.
   cargo test --manifest-path /path/to/independent-consumer/Cargo.toml --features ssr
   cargo build --manifest-path /path/to/independent-consumer/Cargo.toml \
     --target wasm32-unknown-unknown --no-default-features --features hydrate

   These commands assume the fixture defines the illustrated forwarding features. Use a separate CSR build too, and browser behavior proofs for actual hydration/interaction. Native test coverage is not numeric WASM coverage.

   A temporary old-package shim may re-export the lower library and, if necessary, view adapters. Neither new owner may depend back on that shim. Document a removal plan and exact API paths rather than preserving a cycle.

   6. Coordinate staged work

   Agree the shared dependency/module map with #15 before editing; both touch locale/theme/presentation ownership. Implement the acyclic extraction first, adapt view, migrate callers and validate parity. Align #14's plugin entry points with this resulting boundary and #16's actual server dependency paths.

   Complete review rounds for complexity, responsibility/abstraction and consistency/Rustdoc. Validate preserved page snapshots/HTML, mounted routing, UI accessibility, cancellation and opt-in streaming. Report native/browser/packaged target evidence separately. No development listener, package publication or dependency upgrade is required by this task.
2. cblanquera

   added 6 commits that reference this issue on Oct 29, 2026

   Add issue #17 design checkpoint (stackpress-leptos extraction)

   ...

   01d2bce

   Record G41: issue #17 removes stackpress-framework-ui outright; each …

   ...

   0c07794

   Extract stackpress-leptos and make framework-view's Leptos integratio…

   ...

   9d22342

   Record issue #17 part 1 as verified and merged

   ...

   68f38b7

   Add an independent stackpress-leptos consumer, graph audits and libra…

   ...

   9b0b418

   Record issue #17 part 2 as verified and merged

   ...

   dcca20a
3. cblanquera

   added

   human review

   on Oct 30, 2026
4. cblanquera

   added 3 commits that reference this issue on Nov 3, 2026

   Review rounds for issue #17 (part 3)

   ...

   a9862d3

   Clarify the facade's leptos feature docs (issue #17 review round 3)

   ...

   26d3f17

   Record issue #17 part 3 as verified and merged

   ...

   047c8a0