Your next page is taking shape...

Opening Your Next Page…

Loading the guide and preparing its examples for you to explore. The page will appear here automatically when it’s ready, so you can keep this view open without refreshing.

Made for Preact. Built to be yours.

Layout Block


Interactive Live Preview
Try it. Make it yours.

Variant 8 of 8

Live Preview and Source

Open
Setting the scene...

Interactive preview

Add This Block

Copy the Complete Composition. This block is editable Preact source. Its variant entrypoint chooses the layout; shared helpers own the responsive frame and the established navigation behavior.

Copy the Source

Copy all files from the Code Tab into src/components/application-shell, preserving the displayed folders. The application-shell-8 folder, shared folder and the application-shell-1 navigation helpers form one source bundle. The helpers do not require mounting Shell 1.

For production, omit application-shell-8/preview.tsx, shared/preview.tsx, shared/preview-data.ts and the demo logo at application-shell-1/assets/kamod-ui-logo.svg. Keep the remaining files and the repository’s License Notice. The blocks package is private: copy the source instead of attempting to install @kamod-ch/blocks/application-shell/application-shell-8 from npm. If you already copied another new shell, reuse matching shared helpers and review local changes before replacing them.

Dependencies

Install only missing dependencies in the application workspace. The menu adapters require Kamod’s useDropdown, portaled DropdownContent and createRovingFocus export from @kamod-ch/ui/lib/interactive. Verify those APIs in your installed UI release.

Install PackagesTerminal
pnpm add @kamod-ch/ui @kamod-ch/icons @kamod-ch/themes preact @preact/signals

Styles and Import

Use the project’s existing Tailwind CSS setup. Import the theme once, ensure Tailwind scans copied files and the installed UI package, then verify a focused control and a sidebar surface in both color modes. The public entrypoint contains no preview data.

src/styles.css4 lines
@import "tailwindcss";
@import "@kamod-ch/themes/theme.css";

/* Add the UI source path documented for your project’s layout. */
src/App.tsx1 line
import { ApplicationShell8 } from "./components/application-shell/application-shell-8";

Continue with Render and Connect the Shell. If the first render is unstyled, follow Source Discovery before adding local color overrides.

Render and Connect

Give the Frame Real Data; Keep Services in Your App. Supply the four required props—brand, navigationGroups, user and breadcrumbs—then place the route’s content inside the shell. It already provides main.

Working Example

src/App.tsx43 lines
import { Button, Input, Label } from "@kamod-ch/ui";
import { useId, useState } from "preact/hooks";
import { ApplicationShell8, type ApplicationShell8Props } from "./components/application-shell/application-shell-8";

type WorkspaceProps = Pick<ApplicationShell8Props,
  "currentPath" | "onNavigate" | "onUserAction">;

export function Workspace(props: WorkspaceProps) {
  const formId = useId();
  const [name, setName] = useState("Kamod workspace");
  const [saved, setSaved] = useState(name);
  const [message, setMessage] = useState("Ready to edit.");
  const dirty = name !== saved;
  return (
    <ApplicationShell8
      {...props}
      brand={{ name: "Kamod UI", href: "/workspace" }}
      navigationGroups={[{ id: "workspace", items: [
        { id: "settings", label: "Settings", href: "/workspace" },
      ] }]}
      user={{ name: "Alex Morgan", email: "alex@example.com" }}
      breadcrumbs={[{ label: "Workspace" }, { label: "Settings" }]}
      footerStatus={<p role="status">{dirty ? "Unsaved changes" : message}</p>}
      footerActions={<>
        <Button type="reset" form={formId} variant="outline" disabled={!dirty}>Discard</Button>
        <Button type="submit" form={formId} disabled={!dirty}>Save</Button>
      </>}
    >
      <h1 class="mb-6 text-2xl font-semibold">Workspace settings</h1>
      <form id={formId} class="space-y-2"
        onSubmit={event => {
          event.preventDefault();
          setSaved(name); // Local demonstration: replace with your service boundary.
          setMessage("Saved in this example.");
        }}
        onReset={event => { event.preventDefault(); setName(saved); }}>
        <Label htmlFor={formId + "-name"}>Workspace name</Label>
        <Input id={formId + "-name"} name="workspace" required value={name}
          onInput={event => setName(event.currentTarget.value)} />
      </form>
    </ApplicationShell8>
  );
}

The example accepts routing and account callbacks from its parent. Ordinary links work without onNavigate. If your router intercepts navigation, preserve modified clicks and call preventDefault() only for the primary clicks it handles. Keep currentPath synchronized with the actual route and supply an explicit active flag when exact URL matching is insufficient.

The footer is outside the form, but its buttons still submit it. The shared formId connects type="submit" and type="reset" controls to the form. Required-field validation runs before submission. The example saves in memory; update the saved baseline only after your service confirms success, retain the draft on failure, and disable duplicate submissions while pending. The shell creates neither requests nor timers.

Routes and Services

Replace the sample identity with account data from your session layer. onUserAction reports account, billing, notifications or logout; none of these operations is implemented by the shell. A hidden navigation link is not an authorization boundary. Your application and service still decide which records and actions are available.

Keep page queries and mutations outside the frame. Pass the current route’s loading, empty, failure and successful content through children. Use Submission and Recovery for saves, and State Ownership when a value appears in more than one panel.

Responsive State

The sidebar uses the familiar desktop collapse and independent mobile sheet. Footer text and controls wrap on narrow screens, retaining full button labels and keyboard order. Sticky positioning follows the nearest scrolling ancestor; avoid introducing an accidental overflow: hidden wrapper. Test with the mobile keyboard open and with longer localized action labels.

Usage PatternTypeScript
import { useState } from "preact/hooks";
import { ApplicationShell8, type ApplicationShell8Props } from "./components/application-shell/application-shell-8";

type WorkspaceProps = Omit<ApplicationShell8Props, "open" | "defaultOpen" | "onOpenChange">;

export function ControlledWorkspace(props: WorkspaceProps) {
  const [open, setOpen] = useState(true);
  return <ApplicationShell8 {...props} open={open} onOpenChange={setOpen} />;
}

Props and Data

A Small, Typed Application Boundary. The variant entrypoint exports ApplicationShell8 and ApplicationShell8Props. Data types reuse the source-backed Shell 1 contracts; the new frame adds a header action slot and persistent action slots.

Component Props

ApplicationShell8 props
Prop / typeDescription
brand
ApplicationShellBrand
Sidebar identity, an optional logo and an optional home or workspace link.
navigationGroups
readonly ApplicationShellNavigationGroup[]
Ordered groups of destinations, with at most one level of child links.
user
ApplicationShellUser
Account name and email, with an optional avatar or custom initials. No session is inferred.
breadcrumbs
readonly ApplicationShellDestination[]
Ordered trail; its last entry is noninteractive. Earlier entries hide below 768px. Empty arrays omit the trail.
children
ComponentChildren
Page content inside the existing main landmark and padded content area. No placeholder content is inserted.
currentPath
string
Exact URL used to match item href values. An item's explicit active value takes precedence; no router or path normalization is applied.
onNavigate
ApplicationShellNavigate
Handles linked brand, breadcrumb and navigation activation, or a leaf action button. Native links still work without it.
onUserAction
(action: ApplicationShellUserAction) => void
Receives an account menu selection. Your app implements the resulting navigation or account operation.
open
boolean
Controls desktop expansion: true expands, false collapses to icons. Update this value in onOpenChange to respond to the toggle.
defaultOpen
boolean
Initial desktop expansion: true (expanded). Ignored when open is supplied. Mobile sheet state is independent.
onOpenChange
(open: boolean) => void
Reports requested desktop expansion in either state mode. Mobile visibility does not call this callback.
class
string
Additional classes merged onto the outer SidebarProvider wrapper.
className
string
Alias for class, merged after it when both are supplied.
headerActions
ComponentChildren
Application-owned actions beside the breadcrumb trail. Keep labels compact; the header wraps at narrow widths.
footerStatus
ComponentChildren
Application-owned status beside the footer actions. Add role=status to changing feedback when it should be announced; the shell does not create live-region behavior.
footerActions
ComponentChildren
Sticky page actions, wrapping at narrow widths. Associate submit/reset buttons with a form using its unique id. Omitting both footer slots removes the footer.

Data Contracts

Navigation groups have stable id values, optional labels and ordered items. Each item has an id and label, optional href, icon, active and disabled, plus at most one level of items. A disabled parent disables its children; absent URLs create action buttons. Supply component references as icons, not already-rendered elements.

See the complete Navigation, Brand, User and Callback Types for individual fields. The authoritative copied definitions live in application-shell-1/types.ts; shared/types.ts extends them. Unknown DOM attributes are not forwarded to the frame.

Inspect This Variant’s Public Entry or read The Shared Frame to see where the layout choices are fixed.

About the Persistent Action Workspace

Give long forms a stable place for save actions and feedback. A sticky footer keeps the next action within reach while the sidebar, breadcrumbs and page content retain their familiar structure.

When to Choose It

Choose this composition for workspace settings, approval flows and record editors that need Save, Discard or Publish beside a concise status message. The footer is a slot for application controls, not a built-in submission engine. For a short read-only dashboard, omit both slots or start with Shell 2 instead.

Composition

The footer follows the page content in document order and uses position: sticky with bottom: 0. It stays in normal flow, so the final content is not hidden behind a fixed overlay. Use footerActions for buttons and footerStatus for a short message. Both slots are optional; omitting both removes the footer entirely.

The layout choice is deliberately small. This excerpt from the Variant Entrypoint selects a composition in ShellFrame. It is implementation context, not an additional component you need to mount.

Usage PatternTypeScript
return <ShellFrame {...props} layout="actions" />;

One Owner for Each Interaction. The core sidebar owns desktop and mobile visibility; the Menu Adapters own keyboard navigation inside dropdowns; your route owns currentPath, breadcrumbs and data. Keep those boundaries when adapting the copy instead of adding another overlay or a duplicate active-item state.

Start with the working example, then use Component Props to add only the controls this workspace needs. children receives the page, and headerActions receives optional tools such as a save button. Keep draft state in the page or its parent when it must survive navigation.

Appearance

A solid semantic bg-background surface and border-t separate the action bar from the page without another theme provider. Keep one primary action and one quieter alternative. Use the shared Button disabled/loading states and Spinner when a request is pending; do not recolor the entire footer for every state change.

Use Sidebar Tokens for the frame and Supported Variants and Sizes for its controls. The composition follows the host’s theme; it does not create another provider or persist a separate appearance preference. Pair bg-sidebar with text-sidebar-foreground; use bg-background and text-foreground for the page. Verify those pairs with actual form fields and empty/error states, not only the preview’s filled panels.

Verify the Journey

Edit a required field, submit invalid data, correct it, save and then discard another edit. Confirm native validation runs before the save handler. Associate a footer submit button with the page form using form and a unique id. The preview saves only in memory; production must retain failed drafts, block duplicate requests and announce the result through an application-owned role="status" message.

Verify the whole navigation journey. Test at 320px, 768px, 1024px and 1440px with light and dark themes, long labels and real page content. Open and close the menu twice, follow a nested destination and exercise the account menu using the keyboard. Confirm focus return after Escape, visible active states and no document-wide horizontal overflow. The preview’s search, selection and action messages are local demonstrations, not backend operations. Use the service integration guidance for callbacks, and responsive state notes for the controls available in this variant.

Read Submission and Recovery for the service boundary. Choose Shell 6 for a contextual inspector, or Shell 7 for route-level settings sections. Compare All Application Shells, then use The Complete Journey Check before shipping your integration.

Prepare for Production

Turn the working preview into a dependable application boundary. Add one real route and one service-backed action before expanding the navigation. The frame supplies structure; your application owns identity, permissions, records and recovery.

Routes and State Ownership

Mount the shell above the changing page. Replacing children should not recreate the sidebar provider on every route. Keep the same component type and avoid a route-dependent key on the shell when users expect their desktop collapse choice to survive. Derive currentPath, breadcrumbs and navigation permissions from the router/session rather than synchronizing another selected-item state.

Use stable IDs for navigation groups and items. Build static navigation outside the component; use useMemo only when its inputs actually change, such as a project ID, locale or permissions. Do not put draft text in those dependencies. Native links remain useful without a router callback; intercept only the clicks your client router handles and preserve modified clicks for opening another tab.

Keep the final breadcrumb descriptive and noninteractive. Pass an empty trail for pages that do not need one. Each shell already supplies a main landmark: start page content with its heading or a section, not a second nested main. Review State Ownership before moving values into global state.

Requests and Cleanup

Cancel work when its owning route changes. The shell does not fetch records or install polling timers. A page that fetches project data should release its request, subscription or observer when it unmounts or changes record. Keep pending and error states next to the action that creates them, and update a saved baseline only after the server confirms the write.

This effect belongs in a route component with projectId, setProject and setError supplied by that page. Import useEffect from preact/hooks. The cancellation guard prevents an obsolete response from replacing a newer project:

Usage PatternTypeScript
useEffect(() => {
  const request = new AbortController();
  async function loadProject() {
    try {
      const response = await fetch("/api/projects/" + encodeURIComponent(projectId), {
        signal: request.signal,
      });
      if (!response.ok) throw new Error("Project could not be loaded.");
      const project = await response.json();
      if (!request.signal.aborted) setProject(project);
    } catch (error) {
      if (!request.signal.aborted) setError(error);
    }
  }
  void loadProject();
  return () => request.abort();
}, [projectId]);

Validate returned data at your service boundary. Clear the previous error and choose whether to keep stale content or display a loading state when the route changes. Aborting a browser request does not undo a server-side mutation; use your service’s retry and deduplication policy for saves. See Submission and Recovery for preserving edits after a failed submission.

Release Checks

Test a real journey, from opening a page to saving a change. These checks belong to your integrated application: the shell supplies the frame, while your router, forms and services supply the behavior. Work through the steps once, then repeat the journey at the sizes and settings below.

Start with one real journey

For example: open a project, change its name, save it and return to the overview. Use realistic records and a test account with limited access as well as a full-access account.

Screen widths
320 · 768 · 1024 · 1440px
Appearance
Light + dark · your app’s theme
Content
Long labels · empty + busy pages
  1. Follow the route

    Try this

    Open a nested destination, refresh that page, then use the browser’s Back and Forward buttons. Collapse and expand the desktop sidebar. On mobile, open the menu and choose a destination. Connect these actions through your router and navigation data.

    Looks right when

    The URL, page heading, active link and breadcrumbs agree. A direct link opens the correct page, selecting a mobile destination closes the sheet, and an unavailable destination does not navigate or run an action.

  2. Take the keyboard route

    Try this

    Put the pointer aside. Use Tab and Shift + Tab to reach the sidebar toggle, links and account menu. Use arrow keys inside the menu, then press Escape. Repeat with the mobile sheet and check the page with a screen reader.

    Looks right when

    Focus is visible and follows a sensible order. Controls announce useful names and their expanded state. Closing a menu or sheet with Escape returns focus to its trigger. After navigation, your app makes the new page heading discoverable.

  3. Give the layout a stretch

    Try this

    Try the screen sizes above with a long page title, translated navigation labels and a wide table. Switch between light and dark, then zoom the browser to 200%. Review Layout and Styling if content spills outside the frame.

    Looks right when

    Text remains readable and controls stay reachable. The document does not scroll sideways; a wide table or editor scrolls inside its own area. Long names remain understandable, and text, focus rings and active items stay clear in both modes.

  4. Keep unfinished work safe

    Try this

    Type a draft, toggle the sidebar and open the account menu before saving. If your page has an inspector or another dismissible panel, close and reopen it. Decide separately what should happen when users leave the route.

    Looks right when

    Shell controls do not erase a page’s draft. State that must survive an unmounted panel lives above that panel. Navigation follows your app’s save, discard or confirmation policy; the shell does not persist drafts for you.

  5. Make the unhappy paths useful

    Try this

    Try a slow request, an empty result, a failed save and an account without access. Give each case a clear message and a useful next action. Follow the submission and recovery guide when connecting a real form.

    Looks right when

    Loading eventually resolves to content or an explanation. Failed saves preserve edits and offer a safe retry. Empty pages explain how to get started. Your service checks permissions even when a navigation item is hidden.

  6. Check the work behind the screen

    Try this

    In a production build, record a route change and a short typing session with realistic data using the browser’s performance tools. Switch records while a request is pending, then leave and revisit the page. Inspect the request and cleanup boundaries.

    Looks right when

    Typing and navigation stay responsive. An old response cannot overwrite the new record, and timers, listeners and subscriptions stop when their owner leaves. Paginate or virtualize long lists when measurements show a need; keep layout in CSS where possible.

Leave a trail for the next release

Record the build or commit, browser, screen size and result in your release notes. For a failure, include the steps, expected behavior and a screenshot or short recording. Fix and repeat that check before calling the journey ready.

Keep the copied shell source and local changes under version control. Compare updates before replacing shared helpers, and rerun the affected checks when routing, permissions or layout change. Turn repeatable failures into focused automated tests; keep a manual keyboard and visual pass as well.

Source and Next Steps

An Original Kamod Composition. This variant builds on the repository’s existing sidebar and account-menu helpers. It is not presented as a numbered port of an external design collection.

The reusable entrypoint is src/components/application-shell/application-shell-8/index.ts after copying. Compare the Repository Source with your installed UI version when an API differs. Keep a note of local layout changes and preserve the repository license when sharing a copy.

Start from the Working Integration, adjust one boundary at a time, and verify the result inside your actual application. Return to the Block Setup Guide for source ownership, routing and production checks.

Take the Next Useful Step

You have the pieces. Put them into one real interaction, keep its state in one place, and check the result with the content your application will actually show.

Connect the Foundation

Return to Bring a Complete Layout into Your App to connect this reference to a working screen. Keep global CSS in one entrypoint and import only the components that screen needs.

Build the Surrounding Screen

Find a neighboring interaction in the Component Library, or start with a complete Block. Replace sample content and destinations before refining the layout; a local class change can stay with the composition.

Make the Result Hold Up

Use shared theme roles for changes that belong everywhere. Then review the whole journey: keyboard focus, long labels, narrow screens and a clear way to recover when something fails.

Keep a link to the source and note your intentional changes. Your next edit should begin with a clear decision, not another search.