@gravitee/graphene-core 3.3.1 → 3.4.0-feat-add-missing-consumer-icons.74dc4d1

package/USAGE_GUIDE.md

@@ -141,41 +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
 
-All pages share a single uniform centered container. No per-page width decisions needed — the container never changes between sibling pages, eliminating layout shifts during navigation.
-
-The layout owns both **padding** and **max-width** at the layout level. Page components must not duplicate either — do NOT add `p-6` / `p-*` / `px-*` / `py-*` or `max-w-*` classes on page-level wrapper divs.
-
-**Decision rule:**
-
-1. Is this a tool/workspace layout (Policy Studio, LLM Studio), observability dashboard, or log/trace explorer? → `useLayoutConfig({ contentVariant: 'full-bleed' })`
-2. Is this a single-column creation/edit form with a back button and a focused workflow (e.g. alert form, plan form, resource wizard, onboarding stepper)? → Wrap content in `<PageFocused>`. Heuristic: if the page has a "← Back" button and its route matches `/new`, `/:id/edit`, or `/:id` under a list page, it's likely a focused form.
-3. Everything else (list pages, detail views, settings, dashboards) → Do nothing. The default centered container handles it.
-
-```tsx
-import { PageFocused } from '@gravitee/graphene-core';
-
-// Wizard/creation page — focused and centered
-function CreateApiPage() {
-  return (
-    <PageFocused>
-      <StepProgress steps={steps} activeStep={step} />
-      <StepContent />
-    </PageFocused>
-  );
-}
-
-// Everything else — just render content directly (no padding, no max-width)
-function ApisPage() {
-  return (
-    <div className="space-y-4">
-      <h2>APIs</h2>
-      <DataTable ... />
-    </div>
-  );
-}
-```
+- 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
 
@@ -325,107 +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
-
-`AppLayout` accepts `contentVariant` to control content area width and padding:
-
-- `"default"` (default) — centered container with standard padding. All standard pages.
-- `"full-bleed"` — no max-width, no padding; content spans edge-to-edge. Tool layouts, observability dashboards, log/trace explorers.
-
-```tsx
-// Default — no change needed, AppLayout applies the centered container automatically
-<AppLayout>
-  <DetailPage />
-</AppLayout>
-
-// 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.
-
-For creation wizards and steppers, wrap content in `<PageFocused>` inside the default container — see **Layout — content width system** above.
+### `contentVariant` — full-bleed content
 
-### `banner` — full-width status slot
+`AppLayout` accepts `contentVariant` to control content area padding:
 
-`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).
+- `"default"` (default) — standard padding on all sides.
+- `"full-bleed"` — no padding; content spans edge-to-edge.
 
-**Shell layout requirement:** If the host shell renders `<AppLayout>` and reads layout config from `LayoutSlotsProvider`, it must forward **both** `banner` and `bannerSticky` slots to `<AppLayout>`:
+Use `full-bleed` for embedded components that manage their own layout grid (Policy Studio, dashboards, full-screen editors):
 
 ```tsx
-<AppLayout
-  banner={slots.banner}
-  bannerSticky={slots.bannerSticky}
-  contentVariant={slots.contentVariant}
-  contextSidebar={slots.contextSidebar}
-  /* …other slot props… */
->
-```
-
-Without this wiring, `useLayoutConfig({ banner: … })` calls from consumer modules have no effect.
-
-**Usage:**
-
-```tsx
-// Direct prop usage
-<AppLayout banner={<DeployStrip />} bannerSticky>
-  <DetailPage />
+<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.
-
-**Migrating inline banners:** If a page currently renders a banner component inline within its page content, move it to `useLayoutConfig`. On unmount or when the status clears, set `banner: null` — `useLayoutConfig` resets owned keys automatically on unmount, so the banner won't linger after navigation.
-
-**Accessibility:** Add `role="status"` and a descriptive `aria-label` on the banner's root element so screen readers announce it as a live region:
-
-**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 role="status" aria-label="Deployment status" 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" aria-hidden="true" />
-      <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 the content width system in consumer modules
-
-Follow these steps to apply the layout width system to an existing consumer module:
-
-1. **Identify all pages** in your module that render inside `AppLayout`.
-2. **Categorize each page:**
-   - **Default** — list pages, detail views, forms, settings, dashboards. No change needed; `AppLayout` applies the centered container automatically.
-   - **PageFocused** — single-column creation wizards or steppers with a back button and a focused workflow (e.g. alert form, plan form, resource wizard, onboarding stepper). Wrap content in `<PageFocused>`. Heuristic: if the page has a "← Back" button and its route matches `/new`, `/:id/edit`, or `/:id` under a list page, it's likely a focused form.
-   - **Full-bleed** — tool layouts (Policy Studio, LLM Studio), observability dashboards, log/trace explorers. Add `useLayoutConfig({ contentVariant: 'full-bleed' }, [])` if not already set.
-3. **Remove page-level padding** — delete `p-6` and any `p-*`, `px-*`, `py-*` classes from the page's root wrapper `<div>`. The layout already provides content padding via the container. This is the most common change — nearly every page will need it.
-4. **Remove ad-hoc width constraints** — delete any `max-w-*` classes on page-level wrapper divs. The design system owns content width.
-5. **Verify** — resize the browser to confirm content stays centered without clipping on narrow viewports.
-
-See `packages/core/snippets/data-table-list-page.tsx` and `creation-wizard-page.tsx` for complete examples.
-
 ### 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.