@gravitee/graphene-core 2.52.0-feat-layout-content-width-tiers.35c2ff9 → 2.52.0-graphene-142-code-editor.aaa181c

package/USAGE_GUIDE.md

@@ -141,62 +141,9 @@ Scale: `0`, `0.5`, `1`, `1.5`, `2`, `2.5`, `3`, `3.5`, `4`, `5`, `6`, `7`, `8`,
 
 `rounded-sm`, `rounded-md`, `rounded-lg`, `rounded-xl` (mapped to semantic `--radius`).
 
-### Layout — content width system
+### Layout
 
-The layout uses a single default container (100rem / 1600px, left-aligned) with two content wrappers for narrower pages:
-
-| Layer | Token | Rem | Tailwind class | When to use |
-|-------|-------|-----|----------------|-------------|
-| Container (default) | `--content-max-width` | `100rem` | `max-w-content` | The shell container. Applied automatically by `AppLayout`. |
-| Full-bleed | N/A | none | N/A | Tool layouts (Policy Studio), observability pages. Set via `useLayoutConfig({ contentVariant: 'full-bleed' })`. |
-| `<PageSection>` | `--content-form-width` | `80rem` | `max-w-form` | Form pages, settings, config views. Wrap page content in this component. |
-| `<PageFocused>` | `--content-focused-width` | `56rem` | `max-w-focused` | Creation wizards, steppers, onboarding flows. Wrap page content in this component. |
-
-**Decision flowchart:**
-
-1. Is this a tool/workspace layout (Policy Studio, LLM Studio, observability)? → `useLayoutConfig({ contentVariant: 'full-bleed' })`
-2. Is this a creation wizard or stepper? → Wrap content in `<PageFocused>`
-3. Is the page primarily forms, settings, or card-based config? → Wrap content in `<PageSection>`
-4. Is the page primarily a DataTable, entity list, or dashboard? → No wrapper needed (fills the 100rem container)
-5. Not sure? → No wrapper. The default container handles most content well.
-
-Content is **left-aligned** (not centered). Width changes between pages only affect the right edge, keeping the left anchor stable during navigation.
-
-```tsx
-import { PageSection, PageFocused } from '@gravitee/graphene-core';
-
-// Form/settings page
-function GeneralSettingsPage() {
-  return (
-    <PageSection>
-      <h2>General</h2>
-      <form>...</form>
-    </PageSection>
-  );
-}
-
-// Wizard/creation page
-function CreateApiPage() {
-  return (
-    <PageFocused>
-      <StepProgress steps={steps} activeStep={step} />
-      <StepContent />
-    </PageFocused>
-  );
-}
-
-// Table page — no wrapper needed
-function ApisPage() {
-  return (
-    <div className="space-y-4">
-      <h2>APIs</h2>
-      <DataTable ... />
-    </div>
-  );
-}
-```
-
-All width values are defined in `rem` so they scale with user font-size preferences and browser zoom. Consumers do not set `max-w-*` classes directly on page wrappers — use the provided components instead.
+- Content max width is defined on the theme token `--container-content` (maps to `--content-max-width`). Use the max-width utility Tailwind emits for that token in your setup.
 
 ## Styling
 
@@ -346,108 +293,27 @@ If you have not migrated to `AppContextBar` yet, keeping the app name as the fir
 
 **Linear breadcrumbs:** When each step maps to a **path string** and React Router’s `navigate`, use **`buildLinearBreadcrumbs(navigate, segments)`** so `ContentHeader` / `useLayoutConfig` get consistent `BreadcrumbEntry[]` without copying the same `onClick` wiring. If the first crumb is a **custom action** (e.g. “back” that is not `navigate('/path')`), build that entry by hand or mix with `buildLinearBreadcrumbs`—see Storybook **Composed/ContentHeader → Linear breadcrumbs from builder** for the canonical route-based pattern. API edge cases are covered in `packages/core/src/lib/breadcrumbs/buildLinearBreadcrumbs.test.ts`.
 
-### `contentVariant` — content width tiers
-
-`AppLayout` accepts `contentVariant` to control content area width and padding:
-
-- `"default"` (default) — `max-w-content` (80rem) with standard padding. Most pages.
-- `"wide"` — `max-w-wide` (100rem) with standard padding. DataTable list pages.
-- `"full-bleed"` — no max-width, no padding; content spans edge-to-edge. Tool layouts and observability pages.
-
-```tsx
-// Default (80rem) — no change needed, AppLayout applies it automatically
-<AppLayout>
-  <DetailPage />
-</AppLayout>
-
-// Wide (100rem) — for DataTable list pages, add one line
-useLayoutConfig({ contentVariant: 'wide' }, []);
-
-// Full-bleed — for tool layouts and observability pages
-useLayoutConfig({ contentVariant: 'full-bleed' }, []);
-```
-
-With `useLayoutConfig` (module federation), a nested page can set `contentVariant` without affecting other layout slots owned by parent components. Each hook only resets the keys it owns on unmount.
-
-#### Artifact-free page transitions
-
-When navigating between pages with different `contentVariant` values, wrap the navigation action in `startLayoutTransition` to eliminate visual overlap artifacts during DOM reconciliation:
-
-```tsx
-import { startLayoutTransition } from '@gravitee/graphene-core';
-
-// In your router or navigation handler (called once, not per-page):
-function useAppNavigate() {
-  const navigate = useNavigate();
-  return useCallback((to: string) => {
-    startLayoutTransition(() => navigate(to));
-  }, [navigate]);
-}
-```
-
-This uses the View Transitions API to capture the old visual state before applying DOM changes, preventing any intermediate "two pages visible" flash. No visible animation is produced; the swap is perceptually instant. Falls back to direct execution in browsers without View Transitions API support.
+### `contentVariant` — full-bleed content
 
-When the user has **Reduce motion** enabled at the OS level (`prefers-reduced-motion: reduce`), view-transition animation duration is `0ms` and navigation is fully instant.
+`AppLayout` accepts `contentVariant` to control content area padding:
 
-### `banner` — full-width status slot
+- `"default"` (default) — standard padding on all sides.
+- `"full-bleed"` — no padding; content spans edge-to-edge.
 
-`AppLayout` accepts a `banner` prop that renders a full-width region above the padded content wrapper but inside the scroll container. Use it for persistent status indicators with an action (deploy status, environment warnings).
+Use `full-bleed` for embedded components that manage their own layout grid (Policy Studio, dashboards, full-screen editors):
 
 ```tsx
-// Direct prop usage
-<AppLayout banner={<DeployStrip />} bannerSticky>
-  <PageContent />
+<AppLayout contentVariant="full-bleed">
+  <PolicyStudio {...props} />
 </AppLayout>
-
-// Module federation via useLayoutConfig
-useLayoutConfig({
-  banner: deployState === 'NEED_REDEPLOY' ? (
-    <DeployStrip onDeploy={handleDeploy} isPending={isPending} />
-  ) : null,
-  bannerSticky: true,
-}, [deployState, handleDeploy, isPending]);
 ```
 
-The banner spans full width regardless of `contentVariant`. When `bannerSticky` is true, it sticks to the top of the scroll area so the action remains reachable while scrolling.
-
-**Button hierarchy:** When a banner contains an action button alongside page content that has its own primary buttons, use an outline treatment on the banner button to avoid competing with the page's primary CTA:
+With `useLayoutConfig` (module federation), a nested page can set `contentVariant` without affecting other layout slots owned by parent components:
 
 ```tsx
-function DeployStrip({ onDeploy, isPending }) {
-  return (
-    <div className="flex items-center gap-2 border-b border-border px-5 py-1.5">
-      <span className="size-1.5 shrink-0 rounded-full bg-warning" />
-      <span className="text-sm text-muted-foreground">Undeployed changes</span>
-      <div className="flex-1" />
-      <button
-        type="button"
-        className="rounded-md border border-warning/25 bg-warning/5 px-2.5 py-0.5 text-sm font-semibold text-warning-foreground transition-colors hover:bg-warning/10 disabled:opacity-50"
-        onClick={onDeploy}
-        disabled={isPending}
-      >
-        {isPending ? 'Deploying…' : 'Deploy API'}
-      </button>
-    </div>
-  );
-}
+useLayoutConfig({ contentVariant: 'full-bleed' }, []);
 ```
 
-See Storybook **Composed/AppLayout → BannerSlot** for the full interactive example.
-
-### Adopting content width tiers in consumer modules
-
-Follow these steps to apply the layout tier system to an existing consumer module:
-
-1. **Identify all pages** in your module that render inside `AppLayout`.
-2. **Categorize each page:**
-   - **Default** — detail views, edit forms, overviews, settings, creation wizards. No change needed; `AppLayout` applies `max-w-content` (80rem) automatically.
-   - **Wide** — any page whose primary content is a `DataTable`. Add `useLayoutConfig({ contentVariant: 'wide' }, [])` at the top of the component.
-   - **Full-bleed** — tool layouts (Policy Studio) or observability pages (dashboards, explorers). Add `useLayoutConfig({ contentVariant: 'full-bleed' }, [])` if not already set.
-3. **Remove ad-hoc width constraints** — delete any `max-w-*` classes on page-level wrapper divs. The design system owns content width.
-4. **Verify** — resize the browser to confirm content centers correctly on wide viewports and doesn't clip on narrow ones.
-
-See `packages/core/snippets/data-table-list-page.tsx` for a complete list-page example with `useLayoutConfig`.
-
 ### Data table (entity list pages)
 
 Use `DataTable` for any entity list — whether the data is fetched page-by-page from an API or loaded in full on the client. The component provides sorting, filtering, pagination, column visibility, row selection, and bulk actions through a composable slot API.