@vectoriox/iox-ui 5.31.1 → 5.32.0

package/src/design-core/node-classes.ts

@@ -52,12 +52,47 @@ export function roleClass(role: unknown): string | null {
     return typeof role === 'string' && ROLE_SHAPE.test(role) ? `${ROLE_PREFIX}${role.replace(/\./g, '-')}` : null;
 }
 
-/** The node shapes this module reads: a serialized node (`props`) or a builder node (`traits[]`). */
+/** The node shapes this module reads: a serialized node (`props`, `styleProps`) or a builder node (`traits[]`, `styleTraits`). */
 export interface DesignClassSource {
     elementStyle?: string | null;
     role?: string | null;
     props?: Readonly<Record<string, unknown>> | null;
     traits?: ReadonlyArray<{ name?: string; default?: unknown }> | null;
+    styleProps?: Readonly<Record<string, unknown>> | null;
+    styleTraits?: ReadonlyArray<{ traits?: ReadonlyArray<{ name?: string; default?: unknown }> }> | null;
+    responsive?: Readonly<Record<string, { styleProps?: Readonly<Record<string, unknown>> } | undefined>> | null;
+}
+
+/** The element style whose wearer is the phone's bottom navigation bar (CC1, R1). */
+export const BOTTOM_BAR_STYLE = 'bottom-bar';
+/** The page reserves the bar's height wherever this class is on the page… */
+export const BAR_RESERVE_CLASS = 'iox-bar-reserve';
+/** …the responsive Breakpoint ids that can hold an override, widest first (a spec pins it to BREAKPOINTS). */
+export const BAR_RESERVE_BREAKPOINTS: ReadonlyArray<string> = ['laptop', 'tablet', 'mobile', 'small'];
+
+function baseDisplayOf(node: DesignClassSource): unknown {
+    if (node.styleProps && 'display' in node.styleProps) return node.styleProps['display'];
+    for (const group of node.styleTraits ?? []) {
+        const hit = group.traits?.find(t => t?.name === 'display');
+        if (hit) return hit.default;
+    }
+    return undefined;
+}
+
+/**
+ * The class that makes the page reserve a bottom bar's height (iox-design.css: `padding-bottom` and
+ * `scroll-padding-bottom`, WCAG 2.4.11), only at the widths where the bar SHOWS: `iox-bar-reserve` when
+ * it shows at every width, `iox-bar-reserve-<bp>` when it is hidden at base and shown from that
+ * breakpoint down (the phone shape's own rule), null when it never shows or is not a bar.
+ */
+export function barReserveClass(node: DesignClassSource | null | undefined): string | null {
+    if (!node || node.elementStyle !== BOTTOM_BAR_STYLE) return null;
+    if (baseDisplayOf(node) !== 'none') return BAR_RESERVE_CLASS;
+    for (const bp of BAR_RESERVE_BREAKPOINTS) {
+        const display = node.responsive?.[bp]?.styleProps?.['display'];
+        if (display !== undefined && display !== 'none') return `${BAR_RESERVE_CLASS}-${bp}`;
+    }
+    return null;
 }
 
 /** A node's `colorScheme`, from `props` (serialized) or its trait (builder). */
@@ -74,15 +109,15 @@ export function hasElementStyleMarker(node: { elementStyle?: string | null } | n
     return elementStyleClass(node?.elementStyle) !== null;
 }
 
-/** The classes a node renders: `'iox-es iox-es-card iox-scheme-inverse'`, or `''` for none. */
+/** The classes a node renders: `'iox-es iox-es-card iox-scheme-inverse'` (+ a bottom bar's reserve class), or `''` for none. */
 export function nodeDesignClasses(node: DesignClassSource | null | undefined): string {
     const marker = elementStyleClass(node?.elementStyle);
-    return [marker ? `${ELEMENT_STYLE_MARKER_CLASS} ${marker}` : '', colorSchemeClass(colorSchemeOf(node)) ?? '', roleClass(node?.role) ?? '']
+    return [marker ? `${ELEMENT_STYLE_MARKER_CLASS} ${marker}` : '', colorSchemeClass(colorSchemeOf(node)) ?? '', roleClass(node?.role) ?? '', barReserveClass(node) ?? '']
         .filter(Boolean).join(' ');
 }
 
 const isDesignClass = (c: string) =>
-    c === ELEMENT_STYLE_MARKER_CLASS || c.startsWith(MARKER_PREFIX) || c.startsWith(SCHEME_PREFIX) || c.startsWith(ROLE_PREFIX);
+    c === ELEMENT_STYLE_MARKER_CLASS || c.startsWith(MARKER_PREFIX) || c.startsWith(SCHEME_PREFIX) || c.startsWith(ROLE_PREFIX) || c.startsWith(BAR_RESERVE_CLASS);
 
 /** Make an element's design classes match the node — the live switch on the canvas and the
  *  component path's one-time stamp. Removes stale ones; touches no other class. */

package/src/generation-core/compose-site.ts

@@ -10,6 +10,7 @@ import {
     RelativeOp, SitePlan, SitePlanSource, SITE_FACT_LABELS, SiteBusiness,
 } from './site-plan.model';
 import { assertValidSitePlan, nextSourceOf, routeParams } from './validate-site-plan';
+import { NavShape, planNavShape } from './nav-shape';
 
 /**
  * THE composer — a Site Plan in, ordinary IOX data out (design-system plan §6b, W1). Deterministic and
@@ -456,6 +457,7 @@ function composeNode(pn: PatternNode, id: string, repeater: RepeaterScope | null
     assertTraits(type, Object.keys(props));
     // Props first: a Heading with no `es` wears its LEVEL's default style.
     const node = create(id, type, props, pn.es ?? null);
+    if (pn.role) node.role = pn.role;
 
     // Words.
     if (words.placeholder) {
@@ -665,13 +667,19 @@ export function composeSite(plan: SitePlan, context: ComposeContext): ComposedSi
         };
     });
 
-    const globals = Object.values(GlobalSlot).map(slot => {
+    let globals = Object.values(GlobalSlot).map(slot => {
         const pattern = patternById(plan.globals[slot]) as SitePattern;
         const node = composePattern(pattern, slot, { ...base, owner: slot, page: null, section: null, nextAlias: null });
         node.isGlobal = true;
         node.globalPosition = pattern.global;
         return node;
     });
+    // CC1: a header pattern that names its phone shape gets it — the same edit the author's "Phone menu"
+    // section makes, so the composed header and a hand-switched one are one structure.
+    for (const slot of Object.values(GlobalSlot)) {
+        const shape = patternById(plan.globals[slot])?.phoneMenu;
+        if (shape) globals = planNavShape(globals, shape as NavShape, {}, slot).globals;
+    }
 
     return {
         source: clone(plan.source),

package/src/generation-core/nav-shape.ts

@@ -0,0 +1,553 @@
+import { LinkType } from '@vectoriox/iox-ui/design-core';
+
+import { PatternGlobalPosition } from './patterns';
+import { createSerializedNode, SerializedNode, walkSerialized } from './serialized-node';
+
+/**
+ * The phone shapes of a navigation bar (complex-components plan CC1, §7a + R1; boards 1–3). ONE pure tree
+ * edit, `planNavShape`, turns a site's header into the shape the author (the Navigation bar's "Phone
+ * menu" section) or the composer (`nav.inline-cta`'s `phoneMenu`) asks for:
+ *
+ * - **Drawer** — a menu button in the header opens a slide-in Dialog at the end edge that lists every
+ *   page (board 1). The drawer is a child of the Navigation bar.
+ * - **Bottom bar** — an app-style bar fixed to the bottom of the screen with up to five pages, no drawer
+ *   (board 2). The phone header keeps only the brand (Q4).
+ * - **Both** — the bar with four pages and More, which opens the drawer; the drawer is then its own
+ *   global, beside the Navigation bar (board 2's layer tree).
+ *
+ * Every part is a real node with a `role` (R2): editable, selectable, styled by its element style. Parts
+ * a shape keeps are passed through untouched, so an author's edits survive a change of shape; the parts
+ * it no longer has are removed (undo brings them back — the caller records ONE history step). Nothing
+ * here reads a clock or a random source: ids come from `newId` (deterministic by default, so the
+ * composer's output is byte-stable).
+ */
+
+export enum NavShape {
+    Drawer = 'drawer',
+    Bar = 'bar',
+    Both = 'both',
+}
+
+/** The roles of a navigation's parts (the composite plan's `role` field, here for the nav). */
+export enum NavRole {
+    Root = 'nav',
+    Brand = 'nav.brand',
+    Links = 'nav.links',
+    Link = 'nav.link',
+    Cta = 'nav.cta',
+    MenuButton = 'nav.menu-button',
+    Drawer = 'nav.drawer',
+    DrawerHead = 'nav.drawer-head',
+    DrawerClose = 'nav.drawer-close',
+    DrawerLinks = 'nav.drawer-links',
+    DrawerLink = 'nav.drawer-link',
+    DrawerCta = 'nav.drawer-cta',
+    Bar = 'nav.bar',
+    BarItem = 'nav.bar-item',
+    More = 'nav.more',
+}
+
+/** The breakpoints a phone menu may switch at (the responsive Breakpoint ids; Q5: Mobile landscape). */
+export enum PhoneMenuBreakpoint {
+    Tablet = 'tablet',
+    Mobile = 'mobile',
+    Small = 'small',
+}
+
+export const DEFAULT_PHONE_MENU_BREAKPOINT = PhoneMenuBreakpoint.Mobile;
+
+/** The bar's item count, More included (Q2: 3–5; iOS and Material both cap at five). */
+export const BAR_ITEMS_MIN = 3;
+export const BAR_ITEMS_MAX = 5;
+
+export interface NavShapeOptions {
+    /** Where the phone shape takes over (≤ this breakpoint). Default Mobile landscape (≤767). */
+    at?: PhoneMenuBreakpoint | `${PhoneMenuBreakpoint}`;
+    /** Items in the bar, More included (3–5). Default: 5 for Bottom bar, 4 + More for Both. */
+    barItems?: number;
+    /** A new part's id (the builder passes its id generator). Default: `<nav id>-<suffix>`. */
+    newId?: (suffix: string) => string;
+}
+
+export interface NavShapeResult {
+    /** The globals after the edit (the Navigation bar edited in place, the drawer/bar added or removed). */
+    globals: SerializedNode[];
+    shape: NavShape;
+    at: PhoneMenuBreakpoint;
+}
+
+export class NavShapeError extends Error {}
+
+const CONTAINER = 'Container';
+const DIALOG = 'Dialog';
+const LINK = 'Link';
+const LINKED = 'LinkedContainer';
+const BUTTON = 'ButtonBlock';
+const ICON = 'Icon';
+const TEXT = 'Text';
+const HEADING = 'Heading';
+const NAV_STYLE = 'nav';
+const DISPLAY = 'display';
+const NONE = 'none';
+const CLICK = 'click';
+const HOME_ROUTE = '/';
+const COMPOSED = { releaseLayoutDefaults: true };
+
+/** The words the parts carry — site copy, editable like any other (the composer writes English copy). */
+export const NAV_SHAPE_COPY = {
+    menu: 'Menu',
+    closeMenu: 'Close menu',
+    more: 'More',
+    home: 'Home',
+} as const;
+
+/** The layer names of the parts (R2: the tree, the breadcrumb and the toolbar read them). */
+export const NAV_PART_LABELS: Readonly<Record<string, string>> = {
+    [NavRole.Root]: 'Navigation bar',
+    [NavRole.Brand]: 'Brand',
+    [NavRole.Links]: 'Links',
+    [NavRole.MenuButton]: 'Menu button',
+    [NavRole.Drawer]: 'Menu drawer',
+    [NavRole.DrawerHead]: 'Drawer header',
+    [NavRole.DrawerClose]: 'Close',
+    [NavRole.DrawerLinks]: 'Drawer links',
+    [NavRole.Bar]: 'Bottom bar',
+    [NavRole.More]: 'More',
+};
+
+/** Phosphor icons for the bar's items by route — there is no page icon field (Q6), so the bar starts here and
+ *  the author picks (the icons are ordinary Icon nodes). */
+const ROUTE_ICONS: ReadonlyArray<[RegExp, string]> = [
+    [/^\/?$/, 'ph-thin ph-house'],
+    [/work|project|portfolio/i, 'ph-thin ph-squares-four'],
+    [/about|studio|team/i, 'ph-thin ph-user'],
+    [/journal|blog|news/i, 'ph-thin ph-book-open'],
+    [/contact/i, 'ph-thin ph-chat-circle'],
+    [/shop|store/i, 'ph-thin ph-bag'],
+];
+const FALLBACK_ICON = 'ph-thin ph-file';
+const MENU_ICON = 'ph-thin ph-list';
+const CLOSE_ICON = 'ph-thin ph-x';
+const MORE_ICON = 'ph-thin ph-dots-three';
+
+export function barIconForRoute(route: string): string {
+    return ROUTE_ICONS.find(([re]) => re.test(route))?.[1] ?? FALLBACK_ICON;
+}
+
+/** One page the navigation links to, read off its links. */
+export interface NavPage {
+    label: string;
+    route: string;
+}
+
+// ── reading ─────────────────────────────────────────────────────────────────────────────────
+
+const roleOf = (n: SerializedNode | null | undefined) => n?.role;
+
+function find(nodes: ReadonlyArray<SerializedNode>, role: NavRole): SerializedNode | null {
+    let hit: SerializedNode | null = null;
+    walkSerialized(nodes, n => { if (!hit && n.role === role) hit = n; });
+    return hit;
+}
+
+function findAll(nodes: ReadonlyArray<SerializedNode>, role: NavRole): SerializedNode[] {
+    const out: SerializedNode[] = [];
+    walkSerialized(nodes, n => { if (n.role === role) out.push(n); });
+    return out;
+}
+
+/** The Navigation bar: the global with the root role, else the first global wearing the `nav` style. */
+export function findNavRoot(globals: ReadonlyArray<SerializedNode>, navId?: string | null): SerializedNode | null {
+    if (navId) return globals.find(g => g.id === navId) ?? null;
+    return globals.find(g => g.role === NavRole.Root) ?? globals.find(g => g.elementStyle === NAV_STYLE && g.type === CONTAINER) ?? null;
+}
+
+/** The shape a site's globals are in now, or null when there is no Navigation bar. */
+export function navShapeOf(globals: ReadonlyArray<SerializedNode>): NavShape | null {
+    if (!findNavRoot(globals)) return null;
+    const bar = !!find(globals, NavRole.Bar);
+    const drawer = !!find(globals, NavRole.Drawer);
+    if (bar && drawer) return NavShape.Both;
+    if (bar) return NavShape.Bar;
+    return drawer ? NavShape.Drawer : null;
+}
+
+const hiddenAt = (n: SerializedNode): string | null =>
+    Object.entries(n.responsive ?? {}).find(([, layer]) => layer?.styleProps?.[DISPLAY] === NONE)?.[0] ?? null;
+
+/** The breakpoint the phone shape takes over at, read off the header's links row (default Mobile). */
+export function navShapeBreakpoint(globals: ReadonlyArray<SerializedNode>): PhoneMenuBreakpoint {
+    const links = find(globals, NavRole.Links);
+    const bp = links ? hiddenAt(links) : null;
+    return (Object.values(PhoneMenuBreakpoint) as string[]).includes(bp ?? '') ? bp as PhoneMenuBreakpoint : DEFAULT_PHONE_MENU_BREAKPOINT;
+}
+
+const prop = (n: SerializedNode, name: string) => n.props?.[name];
+const isPageLink = (n: SerializedNode) => prop(n, 'linkType') === LinkType.Page && typeof prop(n, 'pageRoute') === 'string';
+
+function textOf(n: SerializedNode): string {
+    if (n.type === LINK) return String(prop(n, 'label') ?? '');
+    let words = '';
+    walkSerialized(n.children ?? [], c => { if (!words && (c.type === TEXT || c.type === HEADING)) words = String(prop(c, 'content') ?? ''); });
+    return words;
+}
+
+/** The pages the header links to, in order: its Links (W1.1 — one plain Link per page in the navigation). */
+export function navPages(root: SerializedNode): NavPage[] {
+    const links = findAll([root], NavRole.Link);
+    const source = links.length ? links : collectHeaderLinks(root);
+    return source.filter(isPageLink).map(n => ({ label: textOf(n), route: String(prop(n, 'pageRoute')) }));
+}
+
+/** A hand-built header: every page Link outside a drawer. */
+function collectHeaderLinks(root: SerializedNode): SerializedNode[] {
+    const out: SerializedNode[] = [];
+    const visit = (n: SerializedNode) => {
+        if (n.type === DIALOG) return;
+        if (n.type === LINK) out.push(n);
+        (n.children ?? []).forEach(visit);
+    };
+    (root.children ?? []).forEach(visit);
+    return out;
+}
+
+// ── building ────────────────────────────────────────────────────────────────────────────────
+
+interface Kit {
+    id: (suffix: string) => string;
+}
+
+/** New ids: the caller's generator, else `<nav id>-<suffix>` made unique against every id already there. */
+function makeKit(globals: ReadonlyArray<SerializedNode>, rootId: string, newId?: (suffix: string) => string): Kit {
+    if (newId) return { id: newId };
+    const used = new Set<string>();
+    walkSerialized(globals, n => used.add(n.id));
+    return {
+        id: (suffix: string) => {
+            const base = `${rootId}-${suffix}`;
+            let id = base;
+            for (let n = 2; used.has(id); n++) id = `${base}-${n}`;
+            used.add(id);
+            return id;
+        },
+    };
+}
+
+/** Point an opener's dialog actions at `dialogId` (a drawer rebuilt under a new id keeps its openers working). */
+function retarget(node: SerializedNode, dialogId: string): SerializedNode {
+    for (const ix of node.interactions as Array<{ actions?: Array<{ type?: string; target?: string }> }>) {
+        for (const a of ix.actions ?? []) if (a.type === 'openDialog' || a.type === 'toggleDialog') a.target = dialogId;
+    }
+    return node;
+}
+
+function part(kit: Kit, suffix: string, type: string, props: Record<string, unknown>, style: string | null, role?: NavRole | null, lay: Record<string, unknown> = {}): SerializedNode {
+    const node = createSerializedNode(kit.id(suffix), type, props, style, COMPOSED);
+    if (role) node.role = role;
+    const label = role ? NAV_PART_LABELS[role] : undefined;
+    if (label) node.label = label;
+    Object.assign(node.styleProps, lay);
+    return node;
+}
+
+function clickTo(kit: Kit, suffix: string, type: 'openDialog' | 'closeDialog', target: string) {
+    return { id: kit.id(`${suffix}-click`), trigger: CLICK, actions: [{ type, target, duration: 0, delay: 0, easing: 'ease' }] };
+}
+
+/** Show at the phone width, hidden above it (base `display: none`, the breakpoint's own `display`). */
+function phoneOnly(node: SerializedNode, at: string, display: string): void {
+    node.styleProps[DISPLAY] = NONE;
+    node.responsive = { ...(node.responsive ?? {}), [at]: { ...(node.responsive?.[at] ?? {}), styleProps: { ...(node.responsive?.[at]?.styleProps ?? {}), [DISPLAY]: display } } };
+}
+
+/** Hidden at the phone width: the header's links row. */
+function hideAt(node: SerializedNode, at: string): void {
+    node.responsive = { ...(node.responsive ?? {}), [at]: { ...(node.responsive?.[at] ?? {}), styleProps: { ...(node.responsive?.[at]?.styleProps ?? {}), [DISPLAY]: NONE } } };
+}
+
+/** Move every `display` override the shape owns to the new breakpoint. */
+function moveDisplayOverride(node: SerializedNode, to: string): void {
+    for (const [bp, layer] of Object.entries(node.responsive ?? {})) {
+        if (bp === to || !layer?.styleProps || !(DISPLAY in layer.styleProps)) continue;
+        const value = layer.styleProps[DISPLAY];
+        const { [DISPLAY]: _drop, ...rest } = layer.styleProps;
+        node.responsive![bp] = { ...layer, styleProps: rest };
+        if (!Object.keys(rest).length && Object.keys(layer).length === 1) delete node.responsive![bp];
+        node.responsive![to] = { ...(node.responsive![to] ?? {}), styleProps: { ...(node.responsive![to]?.styleProps ?? {}), [DISPLAY]: value } };
+    }
+}
+
+function iconNode(kit: Kit, suffix: string, iconClass: string): SerializedNode {
+    return part(kit, suffix, ICON, { iconClass }, null);
+}
+
+function labelText(kit: Kit, suffix: string, words: string): SerializedNode {
+    return part(kit, suffix, TEXT, { content: words, tag: 'span' }, 'button-label');
+}
+
+function menuButton(kit: Kit, drawerId: string, at: string): SerializedNode {
+    const btn = part(kit, 'menu', BUTTON, { tag: 'button', ariaLabel: NAV_SHAPE_COPY.menu }, 'button-ghost', NavRole.MenuButton,
+        { width: '48px', height: '48px', alignItems: 'center', justifyContent: 'center' });
+    btn.children = [iconNode(kit, 'menu-icon', MENU_ICON)];
+    btn.interactions = [clickTo(kit, 'menu', 'openDialog', drawerId)];
+    phoneOnly(btn, at, 'inline-flex');
+    return btn;
+}
+
+function pageLink(kit: Kit, suffix: string, page: NavPage, role: NavRole, lay: Record<string, unknown> = {}): SerializedNode {
+    return part(kit, suffix, LINK, { label: page.label, linkType: LinkType.Page, pageRoute: page.route }, 'link', role, lay);
+}
+
+function drawer(kit: Kit, root: SerializedNode, pages: NavPage[], at: string): SerializedNode {
+    const dr = part(kit, 'drawer', DIALOG, {
+        placement: 'end', closeOnBackdrop: true, showCloseButton: false, ariaLabel: NAV_SHAPE_COPY.menu, closeAbove: at,
+    }, 'dialog', NavRole.Drawer, { width: '86vw', maxWidth: '360px', display: 'flex', flexDirection: 'column', gap: '20px' });
+    const brandWords = textOf(find([root], NavRole.Brand) ?? root) || NAV_PART_LABELS[NavRole.Root];
+    const head = part(kit, 'drawer-head', CONTAINER, {}, 'box', NavRole.DrawerHead,
+        { display: 'flex', justifyContent: 'space-between', alignItems: 'center', gap: '12px' });
+    const close = part(kit, 'drawer-close', BUTTON, { tag: 'button', ariaLabel: NAV_SHAPE_COPY.closeMenu }, 'button-ghost', NavRole.DrawerClose,
+        { width: '44px', height: '44px', alignItems: 'center', justifyContent: 'center' });
+    close.children = [iconNode(kit, 'drawer-close-icon', CLOSE_ICON)];
+    close.interactions = [clickTo(kit, 'drawer-close', 'closeDialog', dr.id)];
+    head.children = [part(kit, 'drawer-brand', HEADING, { content: brandWords, level: 'h3' }, 'h3'), close];
+    const list = part(kit, 'drawer-links', CONTAINER, {}, 'box', NavRole.DrawerLinks,
+        { display: 'flex', flexDirection: 'column', gap: '4px' });
+    // Board 1: every page, Home first, at lead size (on each Link: a Link's own baseline font size would
+    // beat one inherited from the list). Only the CURRENT page is underlined — the shared CSS keys that on
+    // the list's role (iox-design.css), so no Link holds a literal over its element style.
+    list.children = withHome(root, pages).map((p, i) => pageLink(kit, `drawer-link-${i}`, p, NavRole.DrawerLink,
+        { display: 'flex', alignItems: 'center', minHeight: '48px', fontSize: 'var(--iox-size-lead)' }));
+    dr.children = [head, list];
+    const cta = find([root], NavRole.Cta);
+    if (cta) {
+        const copy = JSON.parse(JSON.stringify(cta)) as SerializedNode;
+        const reid = (n: SerializedNode, path: string) => { n.id = kit.id(path); (n.children ?? []).forEach((c, i) => reid(c, `${path}-${i}`)); };
+        reid(copy, 'drawer-cta');
+        copy.role = NavRole.DrawerCta;
+        copy.styleProps = { ...copy.styleProps, alignSelf: 'stretch' };
+        dr.children.push(copy);
+    }
+    return dr;
+}
+
+function barItem(kit: Kit, i: number, page: NavPage): SerializedNode {
+    const item = part(kit, `bar-item-${i}`, LINKED, { linkType: LinkType.Page, pageRoute: page.route, target: '_self' }, 'bottom-bar-item', NavRole.BarItem, BAR_ITEM_LAY);
+    item.label = page.label;
+    item.children = [iconNode(kit, `bar-item-${i}-icon`, barIconForRoute(page.route)), labelText(kit, `bar-item-${i}-label`, page.label)];
+    return item;
+}
+
+const BAR_ITEM_LAY = {
+    display: 'flex', flexDirection: 'column', alignItems: 'center', justifyContent: 'center', gap: '3px',
+    flexGrow: '1', flexShrink: '1', flexBasis: '0px', minWidth: '0px', minHeight: '52px', padding: '4px 2px', textDecoration: 'none',
+};
+
+function moreItem(kit: Kit, drawerId: string): SerializedNode {
+    const more = part(kit, 'bar-more', BUTTON, { tag: 'button' }, 'bottom-bar-item', NavRole.More, BAR_ITEM_LAY);
+    more.children = [iconNode(kit, 'bar-more-icon', MORE_ICON), labelText(kit, 'bar-more-label', NAV_SHAPE_COPY.more)];
+    more.interactions = [clickTo(kit, 'bar-more', 'openDialog', drawerId)];
+    return more;
+}
+
+/** Home first, then the header's pages: the header reaches Home through its brand, a phone menu names it. */
+function withHome(root: SerializedNode, pages: NavPage[]): NavPage[] {
+    const brand = find([root], NavRole.Brand);
+    const home = brand && isPageLink(brand) && prop(brand, 'pageRoute') === HOME_ROUTE && !pages.some(p => p.route === HOME_ROUTE)
+        ? [{ label: NAV_SHAPE_COPY.home, route: HOME_ROUTE }] : [];
+    return [...home, ...pages];
+}
+
+/** The bar's pages: Home first (a bottom bar's customary first stop), capped. */
+function barPages(root: SerializedNode, pages: NavPage[], count: number): NavPage[] {
+    return withHome(root, pages).slice(0, count);
+}
+
+function bar(kit: Kit, root: SerializedNode, pages: NavPage[], shape: NavShape, count: number, drawerId: string | null, at: string): SerializedNode {
+    // The node IS fixed (not only its element style): the builder canvas forces a node's own `position`
+    // with !important, so a stored `static` default would pin the bar into the flow there.
+    const b = part(kit, 'bar', CONTAINER, { htmlTag: 'nav' }, 'bottom-bar', NavRole.Bar,
+        { position: 'fixed', justifyContent: 'space-around', alignItems: 'stretch', gap: '4px', padding: '6px 8px', width: 'auto' });
+    phoneOnly(b, at, 'flex');
+    const itemCount = shape === NavShape.Both ? count - 1 : count;
+    b.children = barPages(root, pages, itemCount).map((p, i) => barItem(kit, i, p));
+    if (shape === NavShape.Both && drawerId) b.children.push(moreItem(kit, drawerId));
+    b.isGlobal = true;
+    b.globalPosition = PatternGlobalPosition.After;
+    return b;
+}
+
+// ── the edit ────────────────────────────────────────────────────────────────────────────────
+
+const clone = <T>(v: T): T => JSON.parse(JSON.stringify(v)) as T;
+
+function removeRole(node: SerializedNode, role: NavRole): SerializedNode | null {
+    let removed: SerializedNode | null = null;
+    const visit = (n: SerializedNode) => {
+        if (!n.children) return;
+        const i = n.children.findIndex(c => c.role === role);
+        if (i >= 0) { removed = n.children[i]; n.children.splice(i, 1); return; }
+        n.children.forEach(visit);
+    };
+    visit(node);
+    return removed;
+}
+
+/** The root's own parts that hide at the phone width: everything but the brand, the menu button and the drawer. */
+function phoneHiddenParts(root: SerializedNode): SerializedNode[] {
+    const keep = new Set<string | undefined>([NavRole.Brand, NavRole.MenuButton, NavRole.Drawer]);
+    return (root.children ?? []).filter((c, i) => !keep.has(roleOf(c)) && !(i === 0 && !c.role && c.type === LINKED));
+}
+
+/** Board 2 / board 8: five items either way — five pages (Bottom bar) or four pages + More (Both). */
+function defaultBarCount(_shape: NavShape): number {
+    return BAR_ITEMS_MAX;
+}
+
+const JUSTIFY = 'justifyContent';
+const CENTER = 'center';
+
+/** Board 2: with a bar, the phone header holds only the brand, centred. The override lives in the phone
+ *  breakpoint's layer only; switching back to the drawer (or moving the breakpoint) removes it. */
+function centerBrandAt(root: SerializedNode, at: string, on: boolean): void {
+    for (const [bp, layer] of Object.entries(root.responsive ?? {})) {
+        if (layer?.styleProps?.[JUSTIFY] !== CENTER) continue;
+        const { [JUSTIFY]: _drop, ...rest } = layer.styleProps;
+        root.responsive![bp] = { ...layer, styleProps: rest };
+    }
+    if (on) root.responsive = { ...(root.responsive ?? {}), [at]: { ...(root.responsive?.[at] ?? {}), styleProps: { ...(root.responsive?.[at]?.styleProps ?? {}), [JUSTIFY]: CENTER } } };
+}
+
+function clampBarCount(n: number | undefined, shape: NavShape): number {
+    const v = Number.isFinite(n) ? Math.round(n as number) : defaultBarCount(shape);
+    return Math.min(BAR_ITEMS_MAX, Math.max(BAR_ITEMS_MIN, v));
+}
+
+/**
+ * Put a site's header into `shape`. The Navigation bar is `navId` or the global carrying the root role
+ * (else the first Container wearing `nav`, which this then marks with roles). Returns new globals;
+ * the input is not mutated.
+ */
+export function planNavShape(globals: ReadonlyArray<SerializedNode>, shape: NavShape, options: NavShapeOptions = {}, navId?: string | null): NavShapeResult {
+    if (!(Object.values(NavShape) as string[]).includes(shape)) throw new NavShapeError(`unknown phone menu shape "${shape}"`);
+    const out = clone(globals) as SerializedNode[];
+    const root = findNavRoot(out, navId);
+    if (!root) throw new NavShapeError('no Navigation bar among the globals');
+    const at = (options.at ?? navShapeBreakpoint(out)) as PhoneMenuBreakpoint;
+    if (!(Object.values(PhoneMenuBreakpoint) as string[]).includes(at)) throw new NavShapeError(`a phone menu cannot switch at "${at}"`);
+    const kit = makeKit(out, root.id, options.newId);
+
+    adoptRoles(root);
+    const pages = navPages(root);
+    const wantDrawer = shape !== NavShape.Bar;
+    const wantBar = shape !== NavShape.Drawer;
+    const wantMenuButton = shape === NavShape.Drawer;
+
+    // The drawer: kept (moved to where the shape puts it) or built; removed for Bar.
+    let dr = removeRole(root, NavRole.Drawer);
+    const topIndex = out.findIndex(g => g.role === NavRole.Drawer);
+    if (!dr && topIndex >= 0) dr = out.splice(topIndex, 1)[0];
+    if (dr) { delete dr.isGlobal; delete dr.globalPosition; }
+    if (wantDrawer && !dr) dr = drawer(kit, root, pages, at);
+    if (!wantDrawer) dr = null;
+    if (dr) dr.props = { ...dr.props, closeAbove: at };
+
+    // The menu button: Drawer only (Q4: with a bar, the phone header keeps only the brand).
+    const existingMenu = removeRole(root, NavRole.MenuButton);
+    const menu = wantMenuButton ? (existingMenu ?? menuButton(kit, dr!.id, at)) : null;
+
+    for (const p of phoneHiddenParts(root)) { moveDisplayOverride(p, at); hideAt(p, at); }
+    centerBrandAt(root, at, wantBar);
+
+    const kids = root.children ?? (root.children = []);
+    if (menu) { moveDisplayOverride(menu, at); kids.push(menu); }
+    if (dr && shape === NavShape.Drawer) kids.push(dr);
+    if (dr && shape === NavShape.Both) {
+        dr.isGlobal = true;
+        dr.globalPosition = PatternGlobalPosition.Before;
+        out.splice(out.indexOf(root) + 1, 0, dr);
+    }
+
+    // The bar: kept (its items are the author's; More follows the shape) or built; removed for Drawer.
+    const barIndex = out.findIndex(g => g.role === NavRole.Bar);
+    let b = barIndex >= 0 ? out.splice(barIndex, 1)[0] : null;
+    let more: SerializedNode | null = null;
+    if (wantBar) {
+        const count = clampBarCount(options.barItems, shape);
+        if (!b) b = bar(kit, root, pages, shape, count, dr?.id ?? null, at);
+        else {
+            moveDisplayOverride(b, at);
+            more = (b.children ?? []).find(c => c.role === NavRole.More) ?? null;
+            b.children = (b.children ?? []).filter(c => c.role !== NavRole.More);
+            if (options.barItems !== undefined) {
+                const items = b.children;
+                const want = shape === NavShape.Both ? count - 1 : count;
+                const extra = barPages(root, pages, BAR_ITEMS_MAX).filter(p => !items.some(c => prop(c, 'pageRoute') === p.route));
+                while (items.length > want) items.pop();
+                while (items.length < want && extra.length) items.push(barItem(kit, items.length, extra.shift()!));
+            }
+            if (shape === NavShape.Both && dr) b.children.push(retarget(more ?? moreItem(kit, dr.id), dr.id));
+        }
+        out.push(b);
+    }
+    return { globals: out, shape, at };
+}
+
+/** Mark a hand-built header's parts with their roles, so every later edit can find them. */
+function adoptRoles(root: SerializedNode): void {
+    root.role = NavRole.Root;
+    const kids = root.children ?? [];
+    const brand = kids.find(c => c.role === NavRole.Brand) ?? (kids[0]?.type === LINKED ? kids[0] : null);
+    if (brand) brand.role = NavRole.Brand;
+    for (const c of kids) {
+        if (c === brand || c.role) continue;
+        if (c.type === CONTAINER && (c.children ?? []).some(k => k.type === LINK)) {
+            c.role = NavRole.Links;
+            for (const k of c.children ?? []) {
+                if (k.role) continue;
+                if (k.type === LINK) k.role = NavRole.Link;
+                else if (k.type === BUTTON) k.role = NavRole.Cta;
+            }
+        }
+    }
+    nameParts(root);
+}
+
+/** Board 3's layer names for the header's own parts, where the author has not named them: Brand, Links,
+ *  and the call to action by its words ("Get in touch"). */
+function nameParts(root: SerializedNode): void {
+    for (const role of [NavRole.Brand, NavRole.Links]) {
+        const part = find([root], role);
+        if (part && !part.label) part.label = NAV_PART_LABELS[role];
+    }
+    const cta = find([root], NavRole.Cta);
+    if (cta && !cta.label) {
+        const words = textOf(cta);
+        if (words) cta.label = words;
+    }
+}
+
+export interface AddBarItemResult {
+    globals: SerializedNode[];
+    /** False when the bar is full (5 items, More included — Q2) or there is no bar. */
+    added: boolean;
+}
+
+/**
+ * The bar's Items list "Add item" (board 2): one more item, before More — the next navigation page the
+ * bar does not link to yet (Home when every page is there). Refused at five (Q2). Input not mutated.
+ */
+export function addBarItem(globals: ReadonlyArray<SerializedNode>, options: Pick<NavShapeOptions, 'newId'> = {}): AddBarItemResult {
+    const out = clone(globals) as SerializedNode[];
+    const root = findNavRoot(out);
+    const b = find(out, NavRole.Bar);
+    if (!root || !b) return { globals: out, added: false };
+    const kids = b.children ?? (b.children = []);
+    if (kids.length >= BAR_ITEMS_MAX) return { globals: out, added: false };
+    const linked = new Set(kids.filter(c => c.role === NavRole.BarItem).map(c => prop(c, 'pageRoute')));
+    const page = barPages(root, navPages(root), BAR_ITEMS_MAX + 1).find(p => !linked.has(p.route))
+        ?? { label: NAV_SHAPE_COPY.home, route: HOME_ROUTE };
+    const item = barItem(makeKit(out, root.id, options.newId), kids.length, page);
+    const more = kids.findIndex(c => c.role === NavRole.More);
+    if (more >= 0) kids.splice(more, 0, item); else kids.push(item);
+    return { globals: out, added: true };
+}