@vectoriox/iox-ui 5.39.0 → 5.40.0

package/generation-core/index.d.ts

@@ -1805,6 +1805,41 @@ declare function parseSampleImageRef(value: unknown): number | null;
  * composer never repairs a plan. `context` carries what the composer may not read for itself (the year).
  */
 declare function composeSite(plan: SitePlan, context: ComposeContext): ComposedSite;
+/** The header pattern the Studio template stamps — and the builder palette's "Navigation bar". */
+declare const SITE_HEADER_PATTERN = "nav.inline-cta";
+/** A page of the studio as the builder lists it. */
+interface SitePageRef {
+    readonly name: string;
+    readonly route: string;
+    readonly isHome?: boolean;
+}
+/** What the header is composed from when there is no Site Plan: the studio's name and its pages. */
+interface NavHeaderInput {
+    readonly business: SiteBusiness;
+    /** Every page of the studio, in the order the navigation should list them. */
+    readonly pages: ReadonlyArray<SitePageRef>;
+}
+interface NavHeaderOptions {
+    /** The header's id; its parts' ids derive from it (`<id>-0-1-…`), so a fresh id gives fresh parts. */
+    readonly id: string;
+    /** A phone-shape part's id (the builder passes its id generator). */
+    readonly newId?: (suffix: string) => string;
+}
+interface ComposedNavHeader {
+    /** The header — a global BEFORE element — carrying the pattern's phone shape (the drawer). */
+    header: SerializedNode;
+    issues: ComposeIssue[];
+}
+/** The pages a navigation links to: every page but Home (the brand links there) and template pages
+ *  (a `/work/:slug` route has no single address), in the studio's order. */
+declare function siteNavPages(pages: ReadonlyArray<SitePageRef>): SitePageRef[];
+/**
+ * The Studio template's header, composed for a studio that has no Site Plan — the builder palette's
+ * "Navigation bar". THE SAME pattern and the same composer as `composeSite`: the brand (the business name),
+ * one plain Link per navigation page, the call to action (W1.1's one dangling-link rule when the studio has
+ * no /contact page: an email to the business, else removed), and the pattern's phone shape. Pure.
+ */
+declare function composeNavHeader(input: NavHeaderInput, options: NavHeaderOptions): ComposedNavHeader;
 
 /**
  * The phone shapes of a navigation bar (complex-components plan CC1, §7a + R1; boards 1–3). ONE pure tree
@@ -1864,6 +1899,8 @@ interface NavShapeOptions {
     barItems?: number;
     /** A new part's id (the builder passes its id generator). Default: `<nav id>-<suffix>`. */
     newId?: (suffix: string) => string;
+    /** The studio's pages, for a header that links to none (a hand-built one): its menu lists these. */
+    pages?: ReadonlyArray<NavPage>;
 }
 interface NavShapeResult {
     /** The globals after the edit (the Navigation bar edited in place, the drawer/bar added or removed). */
@@ -1896,6 +1933,18 @@ declare function navShapeOf(globals: ReadonlyArray<SerializedNode>): NavShape |
 declare function navShapeBreakpoint(globals: ReadonlyArray<SerializedNode>): PhoneMenuBreakpoint;
 /** The pages the header links to, in order: its Links (W1.1 — one plain Link per page in the navigation). */
 declare function navPages(root: SerializedNode): NavPage[];
+/** Where a phone menu's pages come from: the header's own page Links, else the studio's pages. */
+declare enum NavPagesSource {
+    Header = "header",
+    Site = "site",
+    None = "none"
+}
+/** The pages a phone menu lists: the header's (`navPages`), else `sitePages` — a hand-built header with no
+ *  page links still gets a working menu. */
+declare function phoneMenuPages(root: SerializedNode, sitePages?: ReadonlyArray<NavPage>): {
+    pages: NavPage[];
+    source: NavPagesSource;
+};
 /**
  * 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;
@@ -1911,7 +1960,19 @@ interface AddBarItemResult {
  * 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.
  */
-declare function addBarItem(globals: ReadonlyArray<SerializedNode>, options?: Pick<NavShapeOptions, 'newId'>): AddBarItemResult;
+declare function addBarItem(globals: ReadonlyArray<SerializedNode>, options?: Pick<NavShapeOptions, 'newId' | 'pages'>): AddBarItemResult;
+interface BarItemsEditResult {
+    globals: SerializedNode[];
+    /** False when nothing changed: no bar, an unknown item, or the bar would drop below three items (Q2). */
+    changed: boolean;
+}
+/**
+ * The bar's Items list "Remove" (board 2): the item goes, More included — refused below three items (Q2:
+ * 3–5), so the bar never shrinks into something a thumb cannot use. Input not mutated.
+ */
+declare function removeBarItem(globals: ReadonlyArray<SerializedNode>, itemId: string): BarItemsEditResult;
+/** The bar's Items list drag-to-reorder (board 2): item `from` moves to `to`. Input not mutated. */
+declare function moveBarItem(globals: ReadonlyArray<SerializedNode>, from: number, to: number): BarItemsEditResult;
 
-export { BAR_ITEMS_MAX, BAR_ITEMS_MIN, BASELINE_ROLES, BaselineRole, BindScope, CardBindTarget, ComposeError, ComposeIssueCode, DANGLING_LINK_CODES, DEFAULT_PHONE_MENU_BREAKPOINT, FACT_KEYS, GlobalSlot, NAV_PART_LABELS, NAV_SHAPE_COPY, NEUTRAL_STYLE_PROPS, NODE_BASELINES, NavRole, NavShape, NavShapeError, PatternDirective, PatternGlobalPosition, PatternOpens, PatternPlaceholder, PatternRecipe, PhoneMenuBreakpoint, PlaceholderKind, PlanDataSourceMode, PlanDataSourceType, RelativeOp, SAMPLE_IMAGE_REF, SITE_FACT_LABELS, SITE_PATTERNS, SITE_PLAN_VERSION, SITE_TEMPLATES, SPEC_SITE_FACTS, SPEC_SITE_PATTERNS, SPEC_SITE_PLAN_SHAPE, SPEC_SITE_TEMPLATES, STUDIO_TEMPLATE, SitePlanError, SitePlanIssueCode, SitePlanSourceKind, SiteTemplateError, SiteTemplateId, addBarItem, altSourceScopes, assertStyleSlots, assertValidSitePlan, barIconForRoute, composeSite, createSerializedNode, findNavRoot, navPages, navShapeBreakpoint, navShapeOf, nextSourceOf, nodeBindPaths, parseSampleImageRef, patternById, patternNeedsBinding, patternNodes, patternOptionalParts, patternScopes, patternSlots, patternTakesBinding, planFromTemplate, planNavShape, releasedLayoutDefaults, requiredShapeKeys, routeParams, sampleImageRef, setStyleProps, shapeKeys, validateSitePlan, walkSerialized };
-export type { AddBarItemResult, CmsDataSourcePlan, ComposeContext, ComposeIssue, ComposedDataSource, ComposedItem, ComposedPage, ComposedPlaceholder, ComposedRoute, ComposedSite, ContentFieldPlan, ContentSeedPlan, ContentTypePlan, CreateNodeOptions, DataSourcePlan, FactKey, NavPage, NavShapeOptions, NavShapeResult, NodeBaseline, PagePlan, PageSectionPlan, PatternNode, RelativeDataSourcePlan, SerializedBinding, SerializedNode, SerializedResponsive, SiteBusiness, SitePattern, SitePlan, SitePlanIssue, SitePlanSource, SitePlanValidation, SiteTemplate, TemplatePlanInput };
+export { BAR_ITEMS_MAX, BAR_ITEMS_MIN, BASELINE_ROLES, BaselineRole, BindScope, CardBindTarget, ComposeError, ComposeIssueCode, DANGLING_LINK_CODES, DEFAULT_PHONE_MENU_BREAKPOINT, FACT_KEYS, GlobalSlot, NAV_PART_LABELS, NAV_SHAPE_COPY, NEUTRAL_STYLE_PROPS, NODE_BASELINES, NavPagesSource, NavRole, NavShape, NavShapeError, PatternDirective, PatternGlobalPosition, PatternOpens, PatternPlaceholder, PatternRecipe, PhoneMenuBreakpoint, PlaceholderKind, PlanDataSourceMode, PlanDataSourceType, RelativeOp, SAMPLE_IMAGE_REF, SITE_FACT_LABELS, SITE_HEADER_PATTERN, SITE_PATTERNS, SITE_PLAN_VERSION, SITE_TEMPLATES, SPEC_SITE_FACTS, SPEC_SITE_PATTERNS, SPEC_SITE_PLAN_SHAPE, SPEC_SITE_TEMPLATES, STUDIO_TEMPLATE, SitePlanError, SitePlanIssueCode, SitePlanSourceKind, SiteTemplateError, SiteTemplateId, addBarItem, altSourceScopes, assertStyleSlots, assertValidSitePlan, barIconForRoute, composeNavHeader, composeSite, createSerializedNode, findNavRoot, moveBarItem, navPages, navShapeBreakpoint, navShapeOf, nextSourceOf, nodeBindPaths, parseSampleImageRef, patternById, patternNeedsBinding, patternNodes, patternOptionalParts, patternScopes, patternSlots, patternTakesBinding, phoneMenuPages, planFromTemplate, planNavShape, releasedLayoutDefaults, removeBarItem, requiredShapeKeys, routeParams, sampleImageRef, setStyleProps, shapeKeys, siteNavPages, validateSitePlan, walkSerialized };
+export type { AddBarItemResult, BarItemsEditResult, CmsDataSourcePlan, ComposeContext, ComposeIssue, ComposedDataSource, ComposedItem, ComposedNavHeader, ComposedPage, ComposedPlaceholder, ComposedRoute, ComposedSite, ContentFieldPlan, ContentSeedPlan, ContentTypePlan, CreateNodeOptions, DataSourcePlan, FactKey, NavHeaderInput, NavHeaderOptions, NavPage, NavShapeOptions, NavShapeResult, NodeBaseline, PagePlan, PageSectionPlan, PatternNode, RelativeDataSourcePlan, SerializedBinding, SerializedNode, SerializedResponsive, SiteBusiness, SitePageRef, SitePattern, SitePlan, SitePlanIssue, SitePlanSource, SitePlanValidation, SiteTemplate, TemplatePlanInput };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectoriox/iox-ui",
-  "version": "5.39.0",
+  "version": "5.40.0",
   "peerDependencies": {
     "@angular/common": ">=20.0.0",
     "@angular/core": ">=20.0.0",

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

@@ -886,3 +886,82 @@ export function composeSite(plan: SitePlan, context: ComposeContext): ComposedSi
         issues,
     };
 }
+
+// ── The site header on its own (CC1.1) ──────────────────────────────────────────────────────────
+
+/** The header pattern the Studio template stamps — and the builder palette's "Navigation bar". */
+export const SITE_HEADER_PATTERN = 'nav.inline-cta';
+
+/** A page of the studio as the builder lists it. */
+export interface SitePageRef {
+    readonly name: string;
+    readonly route: string;
+    readonly isHome?: boolean;
+}
+
+/** What the header is composed from when there is no Site Plan: the studio's name and its pages. */
+export interface NavHeaderInput {
+    readonly business: SiteBusiness;
+    /** Every page of the studio, in the order the navigation should list them. */
+    readonly pages: ReadonlyArray<SitePageRef>;
+}
+
+export interface NavHeaderOptions {
+    /** The header's id; its parts' ids derive from it (`<id>-0-1-…`), so a fresh id gives fresh parts. */
+    readonly id: string;
+    /** A phone-shape part's id (the builder passes its id generator). */
+    readonly newId?: (suffix: string) => string;
+}
+
+export interface ComposedNavHeader {
+    /** The header — a global BEFORE element — carrying the pattern's phone shape (the drawer). */
+    header: SerializedNode;
+    issues: ComposeIssue[];
+}
+
+const ROUTE_PARAM = ':';
+const HOME_PATH = '/';
+const KEY_UNSAFE = /[^a-z0-9]+/gi;
+
+/** The pages a navigation links to: every page but Home (the brand links there) and template pages
+ *  (a `/work/:slug` route has no single address), in the studio's order. */
+export function siteNavPages(pages: ReadonlyArray<SitePageRef>): SitePageRef[] {
+    return pages.filter(p => !!p.route && !p.isHome && p.route !== HOME_PATH && !p.route.includes(ROUTE_PARAM));
+}
+
+function navPagePlans(pages: ReadonlyArray<SitePageRef>): PagePlan[] {
+    const used = new Set<string>();
+    return pages.map((p, i) => {
+        let key = p.route.replace(KEY_UNSAFE, '-').replace(/^-+|-+$/g, '').toLowerCase() || `page-${i}`;
+        for (let n = 2; used.has(key); n++) key = `${key}-${n}`;
+        used.add(key);
+        return { key, name: p.name, route: p.route, inNav: true, isHome: p.isHome === true, sections: [] };
+    });
+}
+
+/**
+ * The Studio template's header, composed for a studio that has no Site Plan — the builder palette's
+ * "Navigation bar". THE SAME pattern and the same composer as `composeSite`: the brand (the business name),
+ * one plain Link per navigation page, the call to action (W1.1's one dangling-link rule when the studio has
+ * no /contact page: an email to the business, else removed), and the pattern's phone shape. Pure.
+ */
+export function composeNavHeader(input: NavHeaderInput, options: NavHeaderOptions): ComposedNavHeader {
+    if (!nonEmpty(options?.id)) throw new ComposeError('composeNavHeader needs the header id');
+    const pattern = patternById(SITE_HEADER_PATTERN) as SitePattern;
+    const all = navPagePlans(input.pages);
+    const navRoutes = new Set(siteNavPages(input.pages).map(p => p.route));
+    const pages = all.map(p => ({ ...p, inNav: navRoutes.has(p.route) }));
+    const plan = { business: input.business, pages, dataSources: [], contentTypes: [] } as unknown as SitePlan;
+    const email = nonEmpty(input.business.facts?.email) ? input.business.facts!.email!.trim() : null;
+    const issues: ComposeIssue[] = [];
+    const ctx: Ctx = {
+        owner: GlobalSlot.Header, page: null, section: null, plan, year: 0, email, navPage: null, nextAlias: null,
+        placeholders: [], issues, routes: new Set(pages.map(p => p.route)),
+    };
+    const root = composePattern(pattern, options.id, ctx);
+    root.isGlobal = true;
+    root.globalPosition = pattern.global;
+    const shape = pattern.phoneMenu as NavShape | undefined;
+    const header = shape ? planNavShape([root], shape, { newId: options.newId }, root.id).globals[0] : root;
+    return { header, issues };
+}

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

@@ -67,6 +67,8 @@ export interface NavShapeOptions {
     barItems?: number;
     /** A new part's id (the builder passes its id generator). Default: `<nav id>-<suffix>`. */
     newId?: (suffix: string) => string;
+    /** The studio's pages, for a header that links to none (a hand-built one): its menu lists these. */
+    pages?: ReadonlyArray<NavPage>;
 }
 
 export interface NavShapeResult {
@@ -199,6 +201,21 @@ export function navPages(root: SerializedNode): NavPage[] {
     return source.filter(isPageLink).map(n => ({ label: textOf(n), route: String(prop(n, 'pageRoute')) }));
 }
 
+/** Where a phone menu's pages come from: the header's own page Links, else the studio's pages. */
+export enum NavPagesSource {
+    Header = 'header',
+    Site = 'site',
+    None = 'none',
+}
+
+/** The pages a phone menu lists: the header's (`navPages`), else `sitePages` — a hand-built header with no
+ *  page links still gets a working menu. */
+export function phoneMenuPages(root: SerializedNode, sitePages: ReadonlyArray<NavPage> = []): { pages: NavPage[]; source: NavPagesSource } {
+    const own = navPages(root);
+    if (own.length) return { pages: own, source: NavPagesSource.Header };
+    return sitePages.length ? { pages: [...sitePages], source: NavPagesSource.Site } : { pages: [], source: NavPagesSource.None };
+}
+
 /** A hand-built header: every page Link outside a drawer. */
 function collectHeaderLinks(root: SerializedNode): SerializedNode[] {
     const out: SerializedNode[] = [];
@@ -439,7 +456,7 @@ export function planNavShape(globals: ReadonlyArray<SerializedNode>, shape: NavS
     const kit = makeKit(out, root.id, options.newId);
 
     adoptRoles(root);
-    const pages = navPages(root);
+    const { pages } = phoneMenuPages(root, options.pages);
     const wantDrawer = shape !== NavShape.Bar;
     const wantBar = shape !== NavShape.Drawer;
     const wantMenuButton = shape === NavShape.Drawer;
@@ -538,7 +555,7 @@ export interface AddBarItemResult {
  * 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 {
+export function addBarItem(globals: ReadonlyArray<SerializedNode>, options: Pick<NavShapeOptions, 'newId' | 'pages'> = {}): AddBarItemResult {
     const out = clone(globals) as SerializedNode[];
     const root = findNavRoot(out);
     const b = find(out, NavRole.Bar);
@@ -546,10 +563,43 @@ export function addBarItem(globals: ReadonlyArray<SerializedNode>, options: Pick
     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))
+    const page = barPages(root, phoneMenuPages(root, options.pages).pages, 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 };
 }
+
+export interface BarItemsEditResult {
+    globals: SerializedNode[];
+    /** False when nothing changed: no bar, an unknown item, or the bar would drop below three items (Q2). */
+    changed: boolean;
+}
+
+function barOf(globals: ReadonlyArray<SerializedNode>): { out: SerializedNode[]; kids: SerializedNode[] | null } {
+    const out = clone(globals) as SerializedNode[];
+    const b = find(out, NavRole.Bar);
+    return { out, kids: b ? (b.children ?? (b.children = [])) : null };
+}
+
+/**
+ * The bar's Items list "Remove" (board 2): the item goes, More included — refused below three items (Q2:
+ * 3–5), so the bar never shrinks into something a thumb cannot use. Input not mutated.
+ */
+export function removeBarItem(globals: ReadonlyArray<SerializedNode>, itemId: string): BarItemsEditResult {
+    const { out, kids } = barOf(globals);
+    const i = kids ? kids.findIndex(c => c.id === itemId) : -1;
+    if (!kids || i < 0 || kids.length <= BAR_ITEMS_MIN) return { globals: out, changed: false };
+    kids.splice(i, 1);
+    return { globals: out, changed: true };
+}
+
+/** The bar's Items list drag-to-reorder (board 2): item `from` moves to `to`. Input not mutated. */
+export function moveBarItem(globals: ReadonlyArray<SerializedNode>, from: number, to: number): BarItemsEditResult {
+    const { out, kids } = barOf(globals);
+    if (!kids || from === to || from < 0 || to < 0 || from >= kids.length || to >= kids.length) return { globals: out, changed: false };
+    const [item] = kids.splice(from, 1);
+    kids.splice(to, 0, item);
+    return { globals: out, changed: true };
+}