ClientCraft.VisualBuilder.Umbraco 0.1.0-alpha.12

Client Craft Visual Builder for Umbraco

Development source lets reusable designs expose rich-text, image and link fields as well as text and toggles. Each placement uses the original Umbraco Tiptap, Media Picker or Link Picker with its Data Type configuration. Shared values are shown read-only until Customize is selected; Use default restores inheritance. Field choices identify unnamed text and image blocks by content summaries, while shared text and link defaults show their saved content. Native picked identities, crops, link targets and formatting are kept, rather than flattened into URLs or HTML strings. Values pass through native editor conversion and validation before instance projection. This extends the existing field contract without new schema or startup writes; it does not upgrade previously captured proof packages automatically.

Navigation supports an optional menu icon independent of its caption. Explicit administrator adoption of native-navigation-icon-v1 adds the native Show menu icon toggle; existing content stays text-only. Keep Menu button text as words and set Settings → Menu button → Icon spacing for the desired device/state. The decorative icon is hidden from assistive technology; the caption remains the button's accessible name. This additive upgrade does not rewrite labels, content, grid configuration or host-owned conflicting fields and never runs automatically at startup.

Navigation also supports Always show menu button, adopted explicitly through native-navigation-disclosure-v1. Turn it on for dropdowns and mega menus at every screen width; leave it off for the existing responsive navigation. Compose the panel with ordinary Area blocks and native links. Optional icons become decorative chevrons in disclosure mode. Menu button settings include width and content alignment. Escape closes the nearest open disclosure and restores its button focus; leaving it by Tab or clicking outside closes it without taking focus. Without JavaScript, links remain visible in the page flow. This additive migration preserves content and custom help text; it does not create product-specific menus or run at application startup.

Numeric style controls let a designer choose a unit before entering a value. That pending choice does not change the saved style or replace an inherited value with zero. It is scoped to the selected breakpoint/state; entering a number applies it, while resetting the field or breakpoint clears it.

Collection authoring identifies each native Area separately: Item template, When no items are available, and When the source is unavailable. The item template repeats for each record; the two optional recovery areas contain ordinary blocks and are shown only for their matching source state. Add a readable message and native linked action where recovery requires one. Successful item previews use the first record; recovery-area previews remain independent of that record.

Media supports optional alternate artwork for tablet, mobile landscape and mobile portrait through native Media pickers. The explicit native-responsive-media-v1 upgrade reuses the original image picker's Data Type and preserves existing selections. Empty alternatives fall back to the larger-screen image. A single native <picture> shares alternative text, decorative status and caption across the versions; existing single-image content keeps its original rendering. The local homepage proof uses this for decorative artwork rather than editable miniature websites.

Accordion design controls include optional first-item top padding, space before the indicator, indicator line height and answer right padding. These use typed, responsive values scoped to that Accordion. Empty first-item spacing preserves the existing item spacing; it is a default-state control rather than an Open-state override. Native disclosure/keyboard behavior remains unchanged. No schema migration is required for these additions to the existing visual-style value contract.

Standalone reusable visual infrastructure for native Umbraco. It does not require ClientCraft.Core, ClientCraft.Sdk or Client Craft platform credentials. Current development source is alpha.10. The initial extraction alpha.7 was published separately through run39161568694; that package does not contain the later generic catalogue. Development source is not a published candidate.

The published extraction contains the four existing generic Block Grid Razor rendering partials, culture-bound published block reading and request-scoped registration. Development alpha.10 pins Umbraco.Community.BlockPreview 5.5.1 for its upstream nested-action correction; that dependency change requires separate qualification. Tenant-specific sections, branding and commercial content remain Website-owned. This is not a complete no-code editor.

Development alpha.10 now also contains architecture v1's generic semantic components and an explicit opt-in native schema installer. This is ongoing source work. Native installation/replay, rendering, media and editor draft persistence have bounded functional evidence. The local homepage pilot has ten saved sections using all nine kinds, with a native draft preview and editable four-item tabs. Feature items optionally pick decorative illustrations; authored text must carry their information. Full branded homepage equivalence and release qualification remain open. Nothing invokes schema installation at startup. See docs/visualbuilder/ARCHITECTURE-V1.md.

Captured alpha.6 passed six native Umbraco17.7.1/SQLite lifecycle stages: before installation, install, replay, upgrade, replay and removal. Nested published/draft content, schema identities and native authentication defaults were retained without Core, SDK or legacy runtime dependencies. Six focused published-block scenarios also passed in their documented source selection. A visible Chromium native editor scenario subsequently passed: edit, draft preview, publication, public rendering and anonymous preview denial. See docs/releases/VISUAL6-NATIVE-EDITOR-QA.md for its exact assembly hashes, screenshots, initial fixture failure and bounded scope. This does not establish production readiness or human artifact approval.

Target: .NET10 and Umbraco17.7.1. Declared native range is [17.7.1,18.0.0); other versions in that range have not been qualified. Removal does not delete customer content/schema. No automatic conversion of existing content is included.

The published extraction can be installed with dotnet add package ClientCraft.VisualBuilder.Umbraco --version 0.1.0-alpha.7. To evaluate the nine-component catalogue, use the development project or an exact qualified candidate; do not assume alpha.7 contains it. Do not use a local feed in production. Future publication requires the complete evidence matrix and explicit candidate selection. The Website imaging dependency graph is separate; the experimental direct ImageSharp4 override's licence error is not a prerequisite for this package release.

The captured alpha.7 archive passed six native standalone lifecycle stages and the two exact-metapackage Chromium scenarios recorded in docs/releases/SECURITY-SUCCESSOR-FINAL-QUALIFICATION.md. These results supplement the historical alpha.6 evidence below; they do not approve future source or certify mobile editing. Integration and ownership details are in docs/visualbuilder/README.md.

Development source also supports an optional native content Area inside Link. Keep it empty for the normal link label, or compose text, titles, images and boxes inside one clickable element. The selected link label remains its accessible name. Nested links and interactive controls are rejected at publication; drafts remain saveable and invalid legacy content falls back to the plain label when rendered. Explicit native authoring adoption advances to native-link-content-v1, updating only the owned page/component-body grid configurations. There are no startup schema writes. The typed style inspector supports Auto margins through the same saved contract as automatic sizes. This does not establish complete Webflow parity or release readiness.

The source style inspector also offers Fit content and Flex, fit content display modes, plus four independent corner radii. Empty corner fields inherit the shared Corner radius; explicit zero keeps a corner square. These are compatible typed-style additions, not new Document Types or automatic content migrations. The homepage qualification content now composes nine shared designs using native Areas and generic blocks; complete homepage fidelity, dynamic providers and interaction authoring remain under development.

Evidence: docs/releases/VISUAL6-NATIVE-LIFECYCLE-QA.md and VISUAL6-PUBLISHED-BLOCKS.md. MIT license in repository LICENSE. Documentation: https://client-craft.com/hub/. Support/security reports: https://client-craft.com/contact/. Do not include credentials in reports.

External data-source registration (development source)

Public CSS/JS use native Razor Class Library Static Web Assets. They live in this project's wwwroot, are included by the SDK in the NuGet package and are delivered under _content/ClientCraft.VisualBuilder.Umbraco/ in the consuming application's published web root. No manual copy into the consuming source repository is required. Public partials resolve application paths with ASP.NET URL helpers; backoffice extension manifests are registered separately through Umbraco's manifest collection. Content links and media remain native picker values with Umbraco URL/crop resolution.

Collections also have optional native empty and unavailable Areas after the explicit native-collection-states-v1 adoption. Designers compose those states with the same permitted blocks as the Item template; no tenant-specific renderer or invented prices are used. Only the matching state renders publicly. Leaving its Area empty preserves the previous behavior of displaying nothing. Adoption adds Area configuration to the two owned grids, preserves existing Item templates and host additions, and does not rewrite or publish documents. It does not run at startup.

The builder owns typed binding contracts and resolution, not Client Craft business sources. A consuming application or integration supplies an IVisualDataProvider and registers it through native Umbraco composition:

using ClientCraft.VisualBuilder.Umbraco.Data;
using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Core.DependencyInjection;

public sealed class CatalogueComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
        => builder.AddVisualDataSource<MyCatalogueProvider>();
}

MyCatalogueProvider is supplied by the consumer and implements Describe() and ResolveAsync(VisualDataContext, CancellationToken). Registration is request-scoped and idempotent by provider implementation type. Distinct providers must declare distinct source keys; the resolver rejects ambiguous catalogues. Source descriptors provide labels and typed fields; resolution returns only public presentation values. The request supplies site/page/culture/preview context. Providers remain responsible for authorizing the actual backing data; authored bindings cannot supply credentials or grant commercial access. Registration does not install schema or call the provider's data integration.

Visual Builder can run without Core, SDK or platform credentials. The standalone sample owns its illustrative providers outside the package. Following the direct-registration decision, Client Craft first-party source implementations belong to ClientCraft.Core, which references Visual Builder and calls this API itself; no extra integration package or runtime metapackage adapter is involved. This does not add a Core dependency to Visual Builder. Installing Core now also installs Visual Builder. The public seller-offers source requires explicit native site enablement; see the Core README. Local integration qualification is separate from publishing a new package.

Sticky regions through native layout wrappers (development source)

A consuming layout may opt a semantic region into the wrapper adapter with <header ccvb-sticky-region>…</header> and @addTagHelper *, ClientCraft.VisualBuilder.Umbraco. The marker is generic and may be used on another appropriate host region. It does not select a brand, install schema or make all headers sticky. In that region, the designer selects Position: Sticky and a Top offset through the existing visual settings. One visible authored sticky element controls the region; preceding content can scroll away while native grid/shared-component wrappers and semantic landmarks remain intact.

The adapter respects responsive CSS, recalculates region size, restores owned host styles on disposal and does not override a later third-party inline change during cleanup. Ambiguous sticky children, auto or unresolved insets, excessive compositions or unavailable targets retain ordinary CSS layout. Computed absolute-length insets (including resolved font/viewport units and browser-resolved percentages) are supported. Native block previews omit enhancement; full-page preview uses the public renderer. Additional dynamically inserted regions require explicit mountStickyRegion(root) ownership/disposal; automatic discovery covers the initial page. This is not support for arbitrary sticky descendants or every containing-block arrangement.

Designer workflow after catalogue adoption

An administrator first adopts the package catalogue and prepares the host's page type and brand resources using the integration steps above. Designers then compose native Umbraco content:

1. Add a Section to the page's Block Grid. Use its native Area to add content, and native resize handles to choose column and row spans. Use Box when a group of children needs its own layout or appearance.
2. Add Title for a heading, choose its semantic heading level, and use its rich-text toolbar to emphasize any part of the wording. Rich text holds paragraphs and lists. Native media and link pickers supply images and destinations.
3. Open a block's Settings to adjust its visual styles. Select the viewport before entering a responsive override. The inherited values and reset controls keep the shared design understandable. A Section's content maximum width controls its inner content independently of its outer background.
4. Use the Link block's appearance as a starting point for text, filled or outline actions. Keep its visible label and destination together in the native picker. Decorative illustrations can be ordinary Media blocks; their alternative text remains an accessibility decision.
5. Save a reusable design in the website's design library and place it using Shared component. Expose the fields or Areas that each placement should edit; the remaining content, layout and styles follow the shared definition. Publish the definition when its shared changes should become public.
6. For repeated dynamic content, choose an available data source in a collection and bind fields in its item template. Source implementations are registered by the consuming application or an installed integration; the standalone package supplies the generic binding and authoring contracts.
7. Use native Save for a draft, Save and preview for the full page, and Save and publish for the public version. Block previews show editing representations: links stay non-navigable and animation playback stays still while composing.

Authoring native animations

Open a saved block's Settings and find Animations. Add a named animation, choose its trigger and responsive screen-width limits, then add steps. Each step has a content-labelled target, property, start/end values, start time, duration and movement curve. Add independent opacity and vertical-movement steps for a rise entrance; give successive content targets later start times for a sequence. The native link picker's visible labels also identify link targets. Explicit editor labels take priority.

Timings are milliseconds from the animation's trigger. “Strong finish” uses cubic-bezier(.22,1,.36,1); “Gentle finish” uses cubic-bezier(.16,1,.3,1). “When the page is ready” runs for the current document; the viewport trigger also offers a run-once choice. Reopen the saved Settings to inspect the retained sequence, then use the full public preview to test playback.

For viewport entrances, Start inside viewport (px) controls the inset from the bottom edge: 0 starts at the edge, while 64 waits until the block crosses 64 pixels inside it. Existing animations without this optional value keep the edge behavior. The value is a whole number from 0 to 4096; changing the trigger preserves the saved inset for a later return to viewport entry.

For page-ready introductions, Play introduction once per session is optional and off by default. Desktop/mobile variants on the same page and block share the session claim. Return visits, history navigation, section-link arrivals and unavailable session storage keep the authored content static. Reduced motion does not claim a session. This setting uses presentation-only session storage; it does not provide identity, authorization or analytics. Other trigger types ignore the setting while preserving it for a later return to page-ready playback.

Browser-native effects preserve authored transforms. Reduced-motion preferences restore authored content. If a browser effect does not become ready within two seconds, that timeline cancels its owned effects and restores the authored appearance; unrelated host effects remain untouched. The same readable static content is available when the animation module cannot load.

Collection choice appearance

Collection Settings → Visitor filters includes Option background, Option border color and Selected outer border width (0–8px). These responsive, typed values style choice buttons independently of dropdown-list borders. Leave them empty to preserve the previous appearance; explicit zero removes the selected extra stroke. Selected border/background colors and selection indicators retain their existing controls. These are presentation values, not pricing or payment rules. No schema migration or content rewrite is required.

Keyboard outlines and smooth motion

The Outline group provides typed color, style, width and offset. Choose Keyboard focus in Style state to style a focus indicator independently of the resting appearance. Empty fields retain existing behavior. Motion's Smooth choice uses the browser's standard ease curve; existing timelines keep their previous default easing. Hover or keyboard focus can animate named child targets without scaling the text or entire card.

Language Switcher

After the explicit native schema upgrade, add Language Switcher to a Section, Box, Navigation or tab panel, including reusable components. Its languages come from the current page's public Umbraco snapshot and its links from Umbraco's native URL provider. It does not search another page or site for a missing translation. Draft-only and unavailable routes are omitted. An invariant page uses the native request culture and remains read-only.

Content offers Language label format (Short code, Native name, English name), Hide globe icon and Accessible navigation name. Short codes preserve the region when multiple published translations share one language. With one available language the output is plain, non-focusable text. With multiple languages it uses the existing accessible disclosure navigation, with a globe by default, keyboard focus, Escape and outside-click dismissal. Without JavaScript the translation links remain available.

Use Settings for responsive typography, color, spacing and shared styles. Menu button styles the language trigger and Menu panel styles the dropdown. Block previews explain the automatic behavior instead of inventing translation links for a reusable definition. This additive migration does not replace existing text blocks or publish content automatically. The consuming website selects and places the block through its CMS content.

Hosts using compiled ModelsBuilder models with BlockPreview should regenerate their normal models after adopting the new Element Type. The standalone qualification host includes the corresponding native published-model contract, as it does for the other catalogue elements.