@wildo-ai/saas-frontend-lib 1.1.5 → 1.1.6

package/dist/esm/components/views/composite-view/CompositeLayout.js.map

@@ -1 +1 @@
-{"version":3,"file":"CompositeLayout.js","sourceRoot":"","sources":["../../../../../../src/components/views/composite-view/CompositeLayout.tsx"],"names":[],"mappings":"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","sourcesContent":["'use client';\n\nimport type { IndicatorVariant } from '@wildo-ai/presets-components-models';\nimport React, { useMemo, type ReactNode } from 'react';\nimport type { ExpandTrigger, SectionConfig } from '@wildo-ai/presets-components-models';\nimport { LabellingTypes } from '@wildo-ai/presets-components-models';\n\nimport {\n  ContentSectionContainer,\n  type ContentSectionDescriptor,\n} from '~wildo-frontend-lib/components/sections/ContentSectionContainer';\n\nimport {\n  buildSectionConfigFromGroup,\n  groupSectionsByAppearance,\n  type SectionGroup,\n} from '~wildo-frontend-lib/components/resources/skeleton/section-consolidation.utils';\nimport { GroupedSectionBody, type SectionProps } from '~wildo-frontend-lib/components/resources/skeleton/Section';\nimport { GroupedSectionHostKind } from '~wildo-frontend-lib/components/resources/skeleton/Section.shared';\nimport {\n  SectionPresentationProvider,\n  type SectionPresentationEntry,\n} from '~wildo-frontend-lib/components/resources/skeleton/SectionPresentationContext';\nimport { useI18n } from '~wildo-frontend-lib/core/i18n/useI18n';\nimport { useOptionalCompositeViewContext } from './CompositeViewContext';\n\nexport interface CompositeLayoutProps {\n  className?: string;\n  children?: ReactNode;\n  containerConfig?: CompositeLayoutContainerConfigOverrides;\n  sectionMetadata?: Record<string, {\n    icon?: React.ReactNode;\n    /** How many things wait in the section, shown on its tab (#1325). */\n    count?: number;\n    countTone?: IndicatorVariant;\n    containerConfig?: CompositeLayoutContainerConfigOverrides;\n  }>;\n  /**\n   * Forwarded to every section-group container (creation-board plan, Phase 4). Pairs with the\n   * `activeSection` override to complete the CONTROLLED contract: an owner that passes\n   * `activeSection` receives every change request here and applies it (typically to the URL);\n   * ignoring the callback while controlling the value freezes the tabs.\n   */\n  onSectionChange?: (sectionId: string | string[]) => void;\n}\n\nexport interface CompositeLayoutContainerConfigOverrides {\n  animated?: boolean;\n  persistState?: boolean;\n  storageKey?: string;\n  hideWhenEmpty?: boolean;\n  showSingleSectionNav?: boolean;\n  fallbackMode?: SectionConfig['mode'];\n  emptyStateMessage?: string;\n  ariaLabel?: string;\n  ariaLabelledBy?: string;\n  triggerLabel?: { open: string; closed: string };\n  allowNone?: boolean;\n  expandTrigger?: ExpandTrigger;\n  showMoreLabel?: string;\n  showLessLabel?: string;\n  completedIcon?: React.ReactNode;\n  nextLabel?: string;\n  previousLabel?: string;\n  completeLabel?: string;\n  /**\n   * CONTROLLED active section for the navigation modes (TABS / VERTICAL_TABS / PILLS) — see the\n   * seam's contract on the section configs (`frontend-forms.shared.schemas.ts`). Rides the same\n   * override merge every other container knob uses, so a composite OWNER can drive the active tab\n   * (deep links, cross-pane navigation) without a bespoke channel.\n   */\n  activeSection?: string;\n}\n\nexport function CompositeLayout({\n  className,\n  children,\n  containerConfig,\n  sectionMetadata,\n  onSectionChange,\n}: CompositeLayoutProps): ReactNode {\n  const compositeViewContext = useOptionalCompositeViewContext();\n  const compositeTranslationRef = compositeViewContext?.viewDefinition.translationRef;\n  const compositeLabelKeys = useMemo(\n    () => (\n      compositeTranslationRef\n        ? [`${LabellingTypes.COMPOSITE_VIEWS}.${compositeTranslationRef}`]\n        : []\n    ),\n    [compositeTranslationRef],\n  );\n  const { tCompositeViewSection } = useI18n({ keys: compositeLabelKeys });\n  const sectionPresentation = useMemo<Record<string, SectionPresentationEntry> | undefined>(() => {\n    const sectionRefs = new Set<string>([\n      ...Object.keys(sectionMetadata ?? {}),\n      ...(compositeViewContext?.viewDefinition.sectionRefs ?? []),\n    ]);\n    if (sectionRefs.size === 0) {\n      return undefined;\n    }\n\n    /*\n     * Words are resolved only for DECLARED section refs. The labelling pipeline plans\n     * `composite_views.<ref>.sections.<section>.*` from `viewDefinition.sectionRefs` and from nothing\n     * else, so a name that reaches this map through `sectionMetadata` alone has no label anyone could\n     * generate — and since #1450 a missing title is its key path, it would show one forever. Such a\n     * section keeps its icon and count and stays untitled, as it always was.\n     */\n    const declaredSectionRefs = new Set<string>(compositeViewContext?.viewDefinition.sectionRefs ?? []);\n    return Object.fromEntries(\n      Array.from(sectionRefs).map((sectionName) => [\n        sectionName,\n        {\n          title: compositeTranslationRef && declaredSectionRefs.has(sectionName)\n            ? tCompositeViewSection(compositeTranslationRef, sectionName, 'title')\n            : undefined,\n          description: compositeTranslationRef && declaredSectionRefs.has(sectionName)\n            ? tCompositeViewSection(compositeTranslationRef, sectionName, 'description')\n            : undefined,\n          icon: sectionMetadata?.[sectionName]?.icon,\n          count: sectionMetadata?.[sectionName]?.count,\n          countTone: sectionMetadata?.[sectionName]?.countTone,\n        },\n      ]),\n    );\n  }, [\n    compositeTranslationRef,\n    compositeViewContext?.viewDefinition.sectionRefs,\n    sectionMetadata,\n    tCompositeViewSection,\n  ]);\n  const renderedChildren = useMemo(\n    () => renderGroupedChildren(children, containerConfig, sectionPresentation, sectionMetadata, onSectionChange),\n    [children, containerConfig, sectionPresentation, sectionMetadata, onSectionChange],\n  );\n\n  return (\n    <SectionPresentationProvider value={{ sectionEntries: sectionPresentation }}>\n      <div className={className} data-composite-layout>\n        {renderedChildren}\n      </div>\n    </SectionPresentationProvider>\n  );\n}\n\nfunction renderGroupedChildren(\n  children: ReactNode,\n  containerConfig?: CompositeLayoutProps['containerConfig'],\n  sectionPresentation?: Record<string, SectionPresentationEntry>,\n  sectionMetadata?: CompositeLayoutProps['sectionMetadata'],\n  onSectionChange?: CompositeLayoutProps['onSectionChange'],\n): ReactNode {\n  const grouped = groupSectionsByAppearance(children);\n\n  return (\n    <>\n      {grouped.items.map((item, idx) => {\n        if (item.type === 'node') {\n          return <React.Fragment key={idx}>{item.node}</React.Fragment>;\n        }\n\n        const { group } = item;\n        const groupedSections = splitCompositeSectionGroupByMetadata(group.sections, sectionMetadata);\n\n        return groupedSections.map((sectionGroup, groupIndex) => {\n          const config = mergeCompositeLayoutContainerConfig(\n            buildSectionConfigFromGroup({\n              ...group,\n              sections: sectionGroup,\n            } as SectionGroup),\n            resolveCompositeLayoutContainerConfig(sectionGroup, containerConfig, sectionMetadata),\n          );\n\n          const sections: ContentSectionDescriptor[] = sectionGroup.map((section) => (\n            buildContentSectionFromLayoutSection(section, sectionPresentation)\n          ));\n\n          return (\n            <ContentSectionContainer\n              key={`composite-group-${group.mode}-${idx}-${groupIndex}`}\n              sections={sections}\n              config={config}\n              onSectionChange={onSectionChange}\n            />\n          );\n        });\n      })}\n    </>\n  );\n}\n\nfunction buildContentSectionFromLayoutSection(\n  section: React.ReactElement<SectionProps>,\n  sectionPresentation?: Record<string, SectionPresentationEntry>,\n): ContentSectionDescriptor {\n  const metadata = sectionPresentation?.[section.props.name];\n\n  return {\n    id: section.props.name,\n    title: metadata?.title,\n    description: metadata?.description,\n    icon: metadata?.icon,\n    count: metadata?.count,\n    countTone: metadata?.countTone,\n    disabled: section.props.disabled,\n    content: (\n      <GroupedSectionBody\n        hostKind={GroupedSectionHostKind.COMPOSITE}\n        sectionProps={section.props}\n        providesHeading={!!metadata?.title}\n      />\n    ),\n  };\n}\n\nfunction resolveCompositeLayoutContainerConfig(\n  sections: React.ReactElement<SectionProps>[],\n  containerConfig?: CompositeLayoutProps['containerConfig'],\n  sectionMetadata?: CompositeLayoutProps['sectionMetadata'],\n): CompositeLayoutContainerConfigOverrides | undefined {\n  const anchoredOverrides = sections\n    .map((section) => sectionMetadata?.[section.props.name]?.containerConfig)\n    .find((value) => value !== undefined);\n\n  if (!containerConfig && !anchoredOverrides) {\n    return undefined;\n  }\n\n  return {\n    ...containerConfig,\n    ...anchoredOverrides,\n  };\n}\n\nfunction mergeCompositeLayoutContainerConfig(\n  config: SectionConfig,\n  overrides?: CompositeLayoutContainerConfigOverrides,\n): SectionConfig {\n  if (!overrides) {\n    return config;\n  }\n\n  return {\n    ...config,\n    ...overrides,\n  } as SectionConfig;\n}\n\nfunction splitCompositeSectionGroupByMetadata(\n  sections: React.ReactElement<SectionProps>[],\n  sectionMetadata?: CompositeLayoutProps['sectionMetadata'],\n): React.ReactElement<SectionProps>[][] {\n  const groups: React.ReactElement<SectionProps>[][] = [];\n\n  for (const section of sections) {\n    const metadataOverrideKey = JSON.stringify(\n      sectionMetadata?.[section.props.name]?.containerConfig ?? null,\n    );\n    const previousGroup = groups[groups.length - 1];\n    if (!previousGroup) {\n      groups.push([section]);\n      continue;\n    }\n\n    const previousSection = previousGroup[previousGroup.length - 1];\n    const previousOverrideKey = JSON.stringify(\n      sectionMetadata?.[previousSection.props.name]?.containerConfig ?? null,\n    );\n\n    if (previousOverrideKey === metadataOverrideKey) {\n      previousGroup.push(section);\n      continue;\n    }\n\n    groups.push([section]);\n  }\n\n  return groups;\n}\n"]}
+{"version":3,"file":"CompositeLayout.js","sourceRoot":"","sources":["../../../../../../src/components/views/composite-view/CompositeLayout.tsx"],"names":[],"mappings":"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","sourcesContent":["'use client';\n\nimport type { IndicatorVariant } from '@wildo-ai/presets-components-models';\nimport React, { useMemo, type ReactNode } from 'react';\nimport type { ExpandTrigger, SectionConfig } from '@wildo-ai/presets-components-models';\nimport { LabellingTypes } from '@wildo-ai/presets-components-models';\nimport { cn } from '~wildo-frontend-lib/core/ui/cn';\n\nimport {\n  ContentSectionContainer,\n  type ContentSectionDescriptor,\n} from '~wildo-frontend-lib/components/sections/ContentSectionContainer';\n\nimport {\n  buildSectionConfigFromGroup,\n  groupSectionsByAppearance,\n  type SectionGroup,\n} from '~wildo-frontend-lib/components/resources/skeleton/section-consolidation.utils';\nimport { GroupedSectionBody, type SectionProps } from '~wildo-frontend-lib/components/resources/skeleton/Section';\nimport { GroupedSectionHostKind } from '~wildo-frontend-lib/components/resources/skeleton/Section.shared';\nimport {\n  SectionPresentationProvider,\n  type SectionPresentationEntry,\n} from '~wildo-frontend-lib/components/resources/skeleton/SectionPresentationContext';\nimport { useI18n } from '~wildo-frontend-lib/core/i18n/useI18n';\nimport { useOptionalCompositeViewContext } from './CompositeViewContext';\n\nexport interface CompositeLayoutProps {\n  className?: string;\n  children?: ReactNode;\n  containerConfig?: CompositeLayoutContainerConfigOverrides;\n  sectionMetadata?: Record<string, {\n    icon?: React.ReactNode;\n    /** How many things wait in the section, shown on its tab (#1325). */\n    count?: number;\n    countTone?: IndicatorVariant;\n    containerConfig?: CompositeLayoutContainerConfigOverrides;\n  }>;\n  /**\n   * Forwarded to every section-group container (creation-board plan, Phase 4). Pairs with the\n   * `activeSection` override to complete the CONTROLLED contract: an owner that passes\n   * `activeSection` receives every change request here and applies it (typically to the URL);\n   * ignoring the callback while controlling the value freezes the tabs.\n   */\n  onSectionChange?: (sectionId: string | string[]) => void;\n}\n\nexport interface CompositeLayoutContainerConfigOverrides {\n  animated?: boolean;\n  persistState?: boolean;\n  storageKey?: string;\n  hideWhenEmpty?: boolean;\n  showSingleSectionNav?: boolean;\n  fallbackMode?: SectionConfig['mode'];\n  emptyStateMessage?: string;\n  ariaLabel?: string;\n  ariaLabelledBy?: string;\n  triggerLabel?: { open: string; closed: string };\n  allowNone?: boolean;\n  expandTrigger?: ExpandTrigger;\n  showMoreLabel?: string;\n  showLessLabel?: string;\n  completedIcon?: React.ReactNode;\n  nextLabel?: string;\n  previousLabel?: string;\n  completeLabel?: string;\n  /**\n   * CONTROLLED active section for the navigation modes (TABS / VERTICAL_TABS / PILLS) — see the\n   * seam's contract on the section configs (`frontend-forms.shared.schemas.ts`). Rides the same\n   * override merge every other container knob uses, so a composite OWNER can drive the active tab\n   * (deep links, cross-pane navigation) without a bespoke channel.\n   */\n  activeSection?: string;\n}\n\nexport function CompositeLayout({\n  className,\n  children,\n  containerConfig,\n  sectionMetadata,\n  onSectionChange,\n}: CompositeLayoutProps): ReactNode {\n  const compositeViewContext = useOptionalCompositeViewContext();\n  const compositeTranslationRef = compositeViewContext?.viewDefinition.translationRef;\n  const compositeLabelKeys = useMemo(\n    () => (\n      compositeTranslationRef\n        ? [`${LabellingTypes.COMPOSITE_VIEWS}.${compositeTranslationRef}`]\n        : []\n    ),\n    [compositeTranslationRef],\n  );\n  const { tCompositeViewSection } = useI18n({ keys: compositeLabelKeys });\n  const sectionPresentation = useMemo<Record<string, SectionPresentationEntry> | undefined>(() => {\n    const sectionRefs = new Set<string>([\n      ...Object.keys(sectionMetadata ?? {}),\n      ...(compositeViewContext?.viewDefinition.sectionRefs ?? []),\n    ]);\n    if (sectionRefs.size === 0) {\n      return undefined;\n    }\n\n    /*\n     * Words are resolved only for DECLARED section refs. The labelling pipeline plans\n     * `composite_views.<ref>.sections.<section>.*` from `viewDefinition.sectionRefs` and from nothing\n     * else, so a name that reaches this map through `sectionMetadata` alone has no label anyone could\n     * generate — and since #1450 a missing title is its key path, it would show one forever. Such a\n     * section keeps its icon and count and stays untitled, as it always was.\n     */\n    const declaredSectionRefs = new Set<string>(compositeViewContext?.viewDefinition.sectionRefs ?? []);\n    return Object.fromEntries(\n      Array.from(sectionRefs).map((sectionName) => [\n        sectionName,\n        {\n          title: compositeTranslationRef && declaredSectionRefs.has(sectionName)\n            ? tCompositeViewSection(compositeTranslationRef, sectionName, 'title')\n            : undefined,\n          description: compositeTranslationRef && declaredSectionRefs.has(sectionName)\n            ? tCompositeViewSection(compositeTranslationRef, sectionName, 'description')\n            : undefined,\n          icon: sectionMetadata?.[sectionName]?.icon,\n          count: sectionMetadata?.[sectionName]?.count,\n          countTone: sectionMetadata?.[sectionName]?.countTone,\n        },\n      ]),\n    );\n  }, [\n    compositeTranslationRef,\n    compositeViewContext?.viewDefinition.sectionRefs,\n    sectionMetadata,\n    tCompositeViewSection,\n  ]);\n  const renderedChildren = useMemo(\n    () => renderGroupedChildren(children, containerConfig, sectionPresentation, sectionMetadata, onSectionChange),\n    [children, containerConfig, sectionPresentation, sectionMetadata, onSectionChange],\n  );\n\n  return (\n    <SectionPresentationProvider value={{ sectionEntries: sectionPresentation }}>\n      {/*\n        Sections stack with the SAME rhythm `DisplayLayout` and `FormLayout` give theirs. This root had no\n        spacing at all, so every composite's sections touched: measured on Wonder Todos, a todo's\n        \"Supporting Tasks\" list ran straight into the \"Progress Metrics\" heading below it. A flex column\n        with `gap` rather than `space-y`, because a section's content is often behind a `LoadingGate`,\n        whose ready wrapper is `display: contents` — a flex gap spaces its children, a margin cannot.\n      */}\n      <div className={cn('flex flex-col gap-section', className)} data-composite-layout>\n        {renderedChildren}\n      </div>\n    </SectionPresentationProvider>\n  );\n}\n\nfunction renderGroupedChildren(\n  children: ReactNode,\n  containerConfig?: CompositeLayoutProps['containerConfig'],\n  sectionPresentation?: Record<string, SectionPresentationEntry>,\n  sectionMetadata?: CompositeLayoutProps['sectionMetadata'],\n  onSectionChange?: CompositeLayoutProps['onSectionChange'],\n): ReactNode {\n  const grouped = groupSectionsByAppearance(children);\n\n  return (\n    <>\n      {grouped.items.map((item, idx) => {\n        if (item.type === 'node') {\n          return <React.Fragment key={idx}>{item.node}</React.Fragment>;\n        }\n\n        const { group } = item;\n        const groupedSections = splitCompositeSectionGroupByMetadata(group.sections, sectionMetadata);\n\n        return groupedSections.map((sectionGroup, groupIndex) => {\n          const config = mergeCompositeLayoutContainerConfig(\n            buildSectionConfigFromGroup({\n              ...group,\n              sections: sectionGroup,\n            } as SectionGroup),\n            resolveCompositeLayoutContainerConfig(sectionGroup, containerConfig, sectionMetadata),\n          );\n\n          const sections: ContentSectionDescriptor[] = sectionGroup.map((section) => (\n            buildContentSectionFromLayoutSection(section, sectionPresentation)\n          ));\n\n          return (\n            <ContentSectionContainer\n              key={`composite-group-${group.mode}-${idx}-${groupIndex}`}\n              sections={sections}\n              config={config}\n              onSectionChange={onSectionChange}\n            />\n          );\n        });\n      })}\n    </>\n  );\n}\n\nfunction buildContentSectionFromLayoutSection(\n  section: React.ReactElement<SectionProps>,\n  sectionPresentation?: Record<string, SectionPresentationEntry>,\n): ContentSectionDescriptor {\n  const metadata = sectionPresentation?.[section.props.name];\n\n  return {\n    id: section.props.name,\n    title: metadata?.title,\n    description: metadata?.description,\n    icon: metadata?.icon,\n    count: metadata?.count,\n    countTone: metadata?.countTone,\n    disabled: section.props.disabled,\n    content: (\n      <GroupedSectionBody\n        hostKind={GroupedSectionHostKind.COMPOSITE}\n        sectionProps={section.props}\n        providesHeading={!!metadata?.title}\n      />\n    ),\n  };\n}\n\nfunction resolveCompositeLayoutContainerConfig(\n  sections: React.ReactElement<SectionProps>[],\n  containerConfig?: CompositeLayoutProps['containerConfig'],\n  sectionMetadata?: CompositeLayoutProps['sectionMetadata'],\n): CompositeLayoutContainerConfigOverrides | undefined {\n  const anchoredOverrides = sections\n    .map((section) => sectionMetadata?.[section.props.name]?.containerConfig)\n    .find((value) => value !== undefined);\n\n  if (!containerConfig && !anchoredOverrides) {\n    return undefined;\n  }\n\n  return {\n    ...containerConfig,\n    ...anchoredOverrides,\n  };\n}\n\nfunction mergeCompositeLayoutContainerConfig(\n  config: SectionConfig,\n  overrides?: CompositeLayoutContainerConfigOverrides,\n): SectionConfig {\n  if (!overrides) {\n    return config;\n  }\n\n  return {\n    ...config,\n    ...overrides,\n  } as SectionConfig;\n}\n\nfunction splitCompositeSectionGroupByMetadata(\n  sections: React.ReactElement<SectionProps>[],\n  sectionMetadata?: CompositeLayoutProps['sectionMetadata'],\n): React.ReactElement<SectionProps>[][] {\n  const groups: React.ReactElement<SectionProps>[][] = [];\n\n  for (const section of sections) {\n    const metadataOverrideKey = JSON.stringify(\n      sectionMetadata?.[section.props.name]?.containerConfig ?? null,\n    );\n    const previousGroup = groups[groups.length - 1];\n    if (!previousGroup) {\n      groups.push([section]);\n      continue;\n    }\n\n    const previousSection = previousGroup[previousGroup.length - 1];\n    const previousOverrideKey = JSON.stringify(\n      sectionMetadata?.[previousSection.props.name]?.containerConfig ?? null,\n    );\n\n    if (previousOverrideKey === metadataOverrideKey) {\n      previousGroup.push(section);\n      continue;\n    }\n\n    groups.push([section]);\n  }\n\n  return groups;\n}\n"]}

package/dist/esm/core/app-shell/AppShellBuildingBlocks.d.ts

@@ -0,0 +1,86 @@
+import React from 'react';
+import { HorizontalPlacement, ShellRegion } from '@wildo-ai/presets-components-models';
+import type { StatusBarPlacement } from '../../core/config/app-level-components.frontend.schemas';
+import type { AppShellLayoutInfo } from './app-shell.schemas';
+/**
+ * Latches the FIRST time the shell becomes ready.
+ *
+ * `isLayoutReady` derives from configuration presence and can drop transiently after bootstrap (an
+ * organization switch reloading config, for example). Replacing the mounted shell with a loading state on such
+ * a drop would unmount every provider and zone below it and destroy navigation state — the failure mode
+ * `AppLoadingGate` documents. So a layout shows its loading state only while this returns `false`.
+ */
+export declare function useAppShellFirstReady(isLayoutReady: boolean): boolean;
+/**
+ * The shell's loading state: a centred spinner on the page background, announced politely. What every layout
+ * shows while `useAppShellFirstReady` says the shell has never been ready — one component rather than a copy per
+ * layout, so the loading state is the same whatever the disposal.
+ */
+export declare function AppShellLoadingState(): React.JSX.Element;
+export interface AppShellProvidersProps {
+    /** The result of `useAppShellLayout()`, computed once by the layout and shared with every outlet. */
+    layout: AppShellLayoutInfo;
+    children: React.ReactNode;
+}
+/**
+ * The providers every shell region reads, and nothing else — they render no DOM of their own:
+ *
+ * - `PortalContainerContext`, holding the `<main>` element `AppShellContentOutlet` registers, so overlays opened
+ *   from any region portal into the content area — or, when the layout renders `AppShellOverlayPortalLayer`, that
+ *   layer instead;
+ * - `HostedComponentInteractionsProvider`, the single owner of the open state and the open hotkey of the
+ *   interactive hosted components (command menu, notification center, quick switcher), which may be hosted in the
+ *   menubar and the sidebar at once.
+ */
+export declare function AppShellProviders({ layout, children }: AppShellProvidersProps): React.JSX.Element;
+/**
+ * A dedicated layer every overlay (dialog, sheet, menu, popover, tooltip) portals into, for a layout whose regions
+ * are TRANSFORMED — a 3D placement. Render it once, inside the providers but OUTSIDE the transformed subtree; the
+ * providers then prefer it to `<main>`. A layout that transforms nothing does not need it.
+ *
+ * It is a zero-size, untransformed, fixed box at the viewport's origin: an overlay positioned `fixed` resolves
+ * against the viewport, one positioned `absolute` against the viewport's origin, so floating content lands where its
+ * trigger is on screen. It carries the stacking tier overlays need above a layout's own layers.
+ */
+export declare function AppShellOverlayPortalLayer(): React.JSX.Element;
+/**
+ * Which region to render, and — for a region that sits at an edge — at which edge. The content area is not
+ * among them: it has its own outlet, because it owns `<main>` and the page.
+ *
+ * `placement` renders the region only when the application configured THAT placement. A layout that places the
+ * same region at two positions — as the default layout does for the sidebar's start and end edges — renders one
+ * outlet per edge. Omitted, the region renders at whatever placement is configured. The type admits only the
+ * placement axis the region has, so a sidebar cannot be asked for a vertical edge and render nothing.
+ */
+export type AppShellRegionOutletProps = {
+    region: ShellRegion.SIDEBAR | ShellRegion.UTILITY_PANEL;
+    placement?: HorizontalPlacement.START | HorizontalPlacement.END;
+} | {
+    region: ShellRegion.STATUS_BAR;
+    placement?: StatusBarPlacement;
+} | {
+    region: ShellRegion.ACTIVITY_BAR | ShellRegion.MENUBAR | ShellRegion.TOOLBAR;
+    placement?: never;
+};
+/**
+ * Renders one shell region's component — the registry-resolved wrapper, with its placement prop — when the
+ * application configures that region (and, if `placement` is given, at that placement). Renders nothing
+ * otherwise, so placing an outlet for every region is always safe.
+ */
+export declare function AppShellRegionOutlet(props: AppShellRegionOutletProps): React.JSX.Element | null;
+export interface AppShellContentOutletProps {
+    /** Classes for the `<main>` element — the layout decides how the content area sizes within its arrangement. */
+    className?: string;
+    /** The route outlet the layout container receives; rendered by the navigation zones while their stack is empty. */
+    children?: React.ReactNode;
+}
+/**
+ * The content area: the `<main>` landmark carrying `ShellRegion.CONTENT`, the navigation zones, and the floating
+ * quick-action button when configured. Its element is registered with `AppShellProviders` as the portal
+ * container, so it must be rendered exactly once, inside the providers.
+ */
+export declare function AppShellContentOutlet({ className, children }: AppShellContentOutletProps): React.JSX.Element;
+/** The shell's overlay layer: navigation dialogs and sheets, then guidance (tours, tooltips, highlights). */
+export declare function AppShellOverlaysOutlet(): React.JSX.Element;
+/** @wildo_source:part:end saas.frontend.app-shell.building-blocks */
+//# sourceMappingURL=AppShellBuildingBlocks.d.ts.map

package/dist/esm/core/app-shell/AppShellBuildingBlocks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AppShellBuildingBlocks.d.ts","sourceRoot":"","sources":["../../../../../src/core/app-shell/AppShellBuildingBlocks.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAsE,MAAM,OAAO,CAAC;AAE3F,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAqC,MAAM,qCAAqC,CAAC;AAe1H,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uEAAuE,CAAC;AAEhH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAoE9D;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,aAAa,EAAE,OAAO,GAAG,OAAO,CAMrE;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,KAAK,CAAC,GAAG,CAAC,OAAO,CAUxD;AAED,MAAM,WAAW,sBAAsB;IACrC,qGAAqG;IACrG,MAAM,EAAE,kBAAkB,CAAC;IAC3B,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,sBAAsB,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAqBjG;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,IAAI,KAAK,CAAC,GAAG,CAAC,OAAO,CAM9D;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,yBAAyB,GACjC;IAAE,MAAM,EAAE,WAAW,CAAC,OAAO,GAAG,WAAW,CAAC,aAAa,CAAC;IAAC,SAAS,CAAC,EAAE,mBAAmB,CAAC,KAAK,GAAG,mBAAmB,CAAC,GAAG,CAAA;CAAE,GAC5H;IAAE,MAAM,EAAE,WAAW,CAAC,UAAU,CAAC;IAAC,SAAS,CAAC,EAAE,kBAAkB,CAAA;CAAE,GAClE;IAAE,MAAM,EAAE,WAAW,CAAC,YAAY,GAAG,WAAW,CAAC,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,KAAK,CAAA;CAAE,CAAC;AAExG;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,yBAAyB,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,GAAG,IAAI,CA8B/F;AAED,MAAM,WAAW,0BAA0B;IACzC,+GAA+G;IAC/G,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mHAAmH;IACnH,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC5B;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,EAAE,0BAA0B,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAW5G;AAED,6GAA6G;AAC7G,wBAAgB,sBAAsB,IAAI,KAAK,CAAC,GAAG,CAAC,OAAO,CAO1D;AACD,qEAAqE"}

package/dist/esm/core/app-shell/AppShellBuildingBlocks.js

@@ -0,0 +1,187 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { createContext, useCallback, useContext, useEffect, useState } from 'react';
+import { ShellRegion, SurfaceVariant } from '@wildo-ai/presets-components-models';
+import { LoadingSpinner } from '../../components/feedback/loading-spinner.js';
+import { Surface } from '../../components/sections/surface.js';
+import { NON_CANONICAL_SHELL_SURFACE_POLICY_OVERRIDE } from '../../core/ui/surface-a11y.utils.js';
+import { ApplicationLevel_ActivityBar } from '../../components/navigation/app-level/ApplicationLevel_ActivityBar.js';
+import { ApplicationLevel_MenuBar } from '../../components/navigation/app-level/ApplicationLevel_MenuBar.js';
+import { ApplicationLevel_QuickActionButton } from '../../components/navigation/app-level/ApplicationLevel_QuickActionButton.js';
+import { ApplicationLevel_Sidebar } from '../../components/navigation/app-level/ApplicationLevel_Sidebar.js';
+import { ApplicationLevel_StatusBar } from '../../components/navigation/app-level/ApplicationLevel_StatusBar.js';
+import { ApplicationLevel_Toolbar } from '../../components/navigation/app-level/ApplicationLevel_Toolbar.js';
+import { ApplicationLevel_UtilityPanel } from '../../components/navigation/app-level/ApplicationLevel_UtilityPanel.js';
+import { HostedComponentInteractionsProvider } from '../../components/navigation/app-level/HostedComponentInteractionsProvider.js';
+import { GuidanceRenderer } from '../../core/guidance/GuidanceRenderer.js';
+import { NavigationContentAreas, NavigationOverlays } from '../../core/navigation/NavigationContentAreas.js';
+import { PortalContainerContext } from './PortalContainerContext.js';
+/** @wildo_source:part:start saas.frontend.app-shell.building-blocks facet:layer:frontend facet:family:app-shell facet:audience:app-developer */
+/**
+ * # App shell building blocks
+ *
+ * The signed-in shell is a LAYOUT — where the regions sit — over parts that do not depend on the layout: the
+ * region components themselves (each resolved from the component registry by its wrapper), the content area,
+ * the overlays, and two providers every region reads. These building blocks are those parts, so a layout
+ * preset only decides the ARRANGEMENT. `AppLayoutPreset_MainContainer_Default` is composed from them, and any
+ * other layout container an application registers should be too — a different arrangement of the same regions,
+ * or, later, an alternative rendering that draws decoration around them.
+ *
+ * A layout preset uses them like this:
+ *
+ * ```tsx
+ * const layout = useAppShellLayout();
+ * const hasBeenReady = useAppShellFirstReady(layout.isLayoutReady);
+ * if (!layout.isLayoutReady && !hasBeenReady) return <AppShellLoadingState />;
+ * return (
+ *   <AppShellProviders layout={layout}>
+ *     <div className="my-arrangement">
+ *       <AppShellRegionOutlet region={ShellRegion.SIDEBAR} placement={HorizontalPlacement.START} />
+ *       <AppShellRegionOutlet region={ShellRegion.MENUBAR} />
+ *       <AppShellContentOutlet className="flex-1 relative min-w-0">{children}</AppShellContentOutlet>
+ *       <AppShellOverlaysOutlet />
+ *     </div>
+ *   </AppShellProviders>
+ * );
+ * ```
+ *
+ * Four rules keep a custom layout correct:
+ *
+ * - **Render `AppShellProviders` exactly once, around the whole shell.** It owns the single open state and the
+ *   single hotkey registration of the command menu, notification center and quick switcher; two copies would
+ *   make one shortcut open two dialogs.
+ * - **Place every region the application configures.** An outlet renders nothing when its region is not
+ *   configured, so placing an outlet is always safe; leaving one out silently drops a region.
+ * - **Render `AppShellContentOutlet` exactly once.** It is the `<main>` landmark, and overlays portal into it —
+ *   unless the layout also renders `AppShellOverlayPortalLayer`, which then takes the overlays instead. A layout that
+ *   transforms its regions (a 3D placement) must render that layer OUTSIDE the transformed subtree: a transformed
+ *   ancestor is the containing block of every `position: fixed` descendant, so a dialog in `<main>` would be confined
+ *   to the pane and a menu would be placed in the wrong coordinates.
+ * - **Give the root `position: relative`, not `isolation: isolate`,** when the theme may declare a background
+ *   layer. That layer is painted in its own stacking context above ordinary in-flow content, so shell text with
+ *   no positioned ancestor is painted UNDER it; positioning the root lifts the whole shell above it. `isolate`
+ *   would also lift it, but would make the shell one stacking context, so an overlay outside the shell with a
+ *   lower z-index (a consent prompt) would paint over the shell's own dialogs.
+ */
+/** The layout decisions `useAppShellLayout()` computed, shared with every outlet below the providers. */
+const AppShellLayoutContext = createContext(null);
+/** Lets the content outlet hand its `<main>` element to the providers, which expose it as the portal container. */
+const AppShellPortalTargetContext = createContext(null);
+/** Lets `AppShellOverlayPortalLayer` hand its element to the providers, which then prefer it over `<main>`. */
+const AppShellOverlayLayerTargetContext = createContext(null);
+function useAppShellLayoutContext(consumer) {
+    const layout = useContext(AppShellLayoutContext);
+    if (!layout) {
+        throw new Error(`${consumer} must be rendered inside <AppShellProviders>, which supplies the layout it places regions from.`);
+    }
+    return layout;
+}
+/**
+ * Latches the FIRST time the shell becomes ready.
+ *
+ * `isLayoutReady` derives from configuration presence and can drop transiently after bootstrap (an
+ * organization switch reloading config, for example). Replacing the mounted shell with a loading state on such
+ * a drop would unmount every provider and zone below it and destroy navigation state — the failure mode
+ * `AppLoadingGate` documents. So a layout shows its loading state only while this returns `false`.
+ */
+export function useAppShellFirstReady(isLayoutReady) {
+    const [hasLayoutBeenReady, setHasLayoutBeenReady] = useState(false);
+    useEffect(() => {
+        if (isLayoutReady)
+            setHasLayoutBeenReady(true);
+    }, [isLayoutReady]);
+    return hasLayoutBeenReady;
+}
+/**
+ * The shell's loading state: a centred spinner on the page background, announced politely. What every layout
+ * shows while `useAppShellFirstReady` says the shell has never been ready — one component rather than a copy per
+ * layout, so the loading state is the same whatever the disposal.
+ */
+export function AppShellLoadingState() {
+    return (_jsx(Surface, { asChild: true, emitPolicyVars: false, variant: SurfaceVariant.SHELL, policyOverride: NON_CANONICAL_SHELL_SURFACE_POLICY_OVERRIDE, children: _jsx("div", { className: "h-screen w-screen bg-background flex items-center justify-center", role: "status", "aria-live": "polite", children: _jsx("div", { className: "text-center", children: _jsx(LoadingSpinner, { size: 32, className: "text-primary mx-auto mb-field", "aria-hidden": "true" }) }) }) }));
+}
+/**
+ * The providers every shell region reads, and nothing else — they render no DOM of their own:
+ *
+ * - `PortalContainerContext`, holding the `<main>` element `AppShellContentOutlet` registers, so overlays opened
+ *   from any region portal into the content area — or, when the layout renders `AppShellOverlayPortalLayer`, that
+ *   layer instead;
+ * - `HostedComponentInteractionsProvider`, the single owner of the open state and the open hotkey of the
+ *   interactive hosted components (command menu, notification center, quick switcher), which may be hosted in the
+ *   menubar and the sidebar at once.
+ */
+export function AppShellProviders({ layout, children }) {
+    const [portalContainer, setPortalContainer] = useState(null);
+    const [overlayLayer, setOverlayLayer] = useState(null);
+    const registerPortalTarget = useCallback((node) => {
+        setPortalContainer(node);
+    }, []);
+    const registerOverlayLayer = useCallback((node) => {
+        setOverlayLayer(node);
+    }, []);
+    return (_jsx(AppShellLayoutContext.Provider, { value: layout, children: _jsx(AppShellPortalTargetContext.Provider, { value: registerPortalTarget, children: _jsx(AppShellOverlayLayerTargetContext.Provider, { value: registerOverlayLayer, children: _jsx(PortalContainerContext.Provider, { value: overlayLayer ?? portalContainer, children: _jsx(HostedComponentInteractionsProvider, { children: children }) }) }) }) }));
+}
+/**
+ * A dedicated layer every overlay (dialog, sheet, menu, popover, tooltip) portals into, for a layout whose regions
+ * are TRANSFORMED — a 3D placement. Render it once, inside the providers but OUTSIDE the transformed subtree; the
+ * providers then prefer it to `<main>`. A layout that transforms nothing does not need it.
+ *
+ * It is a zero-size, untransformed, fixed box at the viewport's origin: an overlay positioned `fixed` resolves
+ * against the viewport, one positioned `absolute` against the viewport's origin, so floating content lands where its
+ * trigger is on screen. It carries the stacking tier overlays need above a layout's own layers.
+ */
+export function AppShellOverlayPortalLayer() {
+    const register = useContext(AppShellOverlayLayerTargetContext);
+    if (!register) {
+        throw new Error('AppShellOverlayPortalLayer must be rendered inside <AppShellProviders>, which exposes it as the portal container.');
+    }
+    return _jsx("div", { ref: register, "data-shell-overlay-layer": "", className: "fixed left-0 top-0 z-50 h-0 w-0" });
+}
+/**
+ * Renders one shell region's component — the registry-resolved wrapper, with its placement prop — when the
+ * application configures that region (and, if `placement` is given, at that placement). Renders nothing
+ * otherwise, so placing an outlet for every region is always safe.
+ */
+export function AppShellRegionOutlet(props) {
+    const layout = useAppShellLayoutContext('AppShellRegionOutlet');
+    const { region, placement } = props;
+    const at = (configured) => placement === undefined || placement === configured ? configured : null;
+    switch (region) {
+        case ShellRegion.ACTIVITY_BAR:
+            return layout.hasActivityBar ? _jsx(ApplicationLevel_ActivityBar, {}) : null;
+        case ShellRegion.MENUBAR:
+            return layout.hasMenubar ? _jsx(ApplicationLevel_MenuBar, {}) : null;
+        case ShellRegion.TOOLBAR:
+            return layout.hasToolbar ? _jsx(ApplicationLevel_Toolbar, {}) : null;
+        case ShellRegion.SIDEBAR: {
+            const sidebarPlacement = at(layout.sidebarPlacement);
+            return layout.hasSidebar && sidebarPlacement ? _jsx(ApplicationLevel_Sidebar, { placement: sidebarPlacement }) : null;
+        }
+        case ShellRegion.UTILITY_PANEL: {
+            const utilityPanelPlacement = at(layout.utilityPanelPlacement);
+            return layout.hasUtilityPanel && utilityPanelPlacement ? _jsx(ApplicationLevel_UtilityPanel, { position: utilityPanelPlacement }) : null;
+        }
+        case ShellRegion.STATUS_BAR: {
+            const statusBarPlacement = at(layout.statusBarPlacement);
+            return layout.hasStatusBar && statusBarPlacement ? _jsx(ApplicationLevel_StatusBar, { placement: statusBarPlacement }) : null;
+        }
+        default: {
+            const unhandled = region;
+            throw new Error(`AppShellRegionOutlet has no rendering for region "${String(unhandled)}".`);
+        }
+    }
+}
+/**
+ * The content area: the `<main>` landmark carrying `ShellRegion.CONTENT`, the navigation zones, and the floating
+ * quick-action button when configured. Its element is registered with `AppShellProviders` as the portal
+ * container, so it must be rendered exactly once, inside the providers.
+ */
+export function AppShellContentOutlet({ className, children }) {
+    const layout = useAppShellLayoutContext('AppShellContentOutlet');
+    const registerPortalTarget = useContext(AppShellPortalTargetContext);
+    return (_jsxs("main", { ref: registerPortalTarget ?? undefined, "data-component-area": ShellRegion.CONTENT, className: className, children: [_jsx(NavigationContentAreas, { routerChildren: children }), layout.hasQuickActionButton && _jsx(ApplicationLevel_QuickActionButton, { placement: "floating" })] }));
+}
+/** The shell's overlay layer: navigation dialogs and sheets, then guidance (tours, tooltips, highlights). */
+export function AppShellOverlaysOutlet() {
+    return (_jsxs(_Fragment, { children: [_jsx(NavigationOverlays, {}), _jsx(GuidanceRenderer, {})] }));
+}
+//# sourceMappingURL=AppShellBuildingBlocks.js.map

package/dist/esm/core/app-shell/AppShellBuildingBlocks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AppShellBuildingBlocks.js","sourceRoot":"","sources":["../../../../../src/core/app-shell/AppShellBuildingBlocks.tsx"],"names":[],"mappings":"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","sourcesContent":["import React, { createContext, useCallback, useContext, useEffect, useState } from 'react';\n\nimport { HorizontalPlacement, ShellRegion, SurfaceVariant, VerticalPlacement } from '@wildo-ai/presets-components-models';\nimport { LoadingSpinner } from '~wildo-frontend-lib/components/feedback/loading-spinner';\nimport { Surface } from '~wildo-frontend-lib/components/sections/surface';\nimport { NON_CANONICAL_SHELL_SURFACE_POLICY_OVERRIDE } from '~wildo-frontend-lib/core/ui/surface-a11y.utils';\nimport { ApplicationLevel_ActivityBar } from '~wildo-frontend-lib/components/navigation/app-level/ApplicationLevel_ActivityBar';\nimport { ApplicationLevel_MenuBar } from '~wildo-frontend-lib/components/navigation/app-level/ApplicationLevel_MenuBar';\nimport { ApplicationLevel_QuickActionButton } from '~wildo-frontend-lib/components/navigation/app-level/ApplicationLevel_QuickActionButton';\nimport { ApplicationLevel_Sidebar } from '~wildo-frontend-lib/components/navigation/app-level/ApplicationLevel_Sidebar';\nimport { ApplicationLevel_StatusBar } from '~wildo-frontend-lib/components/navigation/app-level/ApplicationLevel_StatusBar';\nimport { ApplicationLevel_Toolbar } from '~wildo-frontend-lib/components/navigation/app-level/ApplicationLevel_Toolbar';\nimport { ApplicationLevel_UtilityPanel } from '~wildo-frontend-lib/components/navigation/app-level/ApplicationLevel_UtilityPanel';\nimport { HostedComponentInteractionsProvider } from '~wildo-frontend-lib/components/navigation/app-level/HostedComponentInteractionsProvider';\nimport { GuidanceRenderer } from '~wildo-frontend-lib/core/guidance/GuidanceRenderer';\nimport { NavigationContentAreas, NavigationOverlays } from '~wildo-frontend-lib/core/navigation/NavigationContentAreas';\n\nimport type { StatusBarPlacement } from '~wildo-frontend-lib/core/config/app-level-components.frontend.schemas';\n\nimport type { AppShellLayoutInfo } from './app-shell.schemas';\nimport { PortalContainerContext } from './PortalContainerContext';\n\n/** @wildo_source:part:start saas.frontend.app-shell.building-blocks facet:layer:frontend facet:family:app-shell facet:audience:app-developer */\n/**\n * # App shell building blocks\n *\n * The signed-in shell is a LAYOUT — where the regions sit — over parts that do not depend on the layout: the\n * region components themselves (each resolved from the component registry by its wrapper), the content area,\n * the overlays, and two providers every region reads. These building blocks are those parts, so a layout\n * preset only decides the ARRANGEMENT. `AppLayoutPreset_MainContainer_Default` is composed from them, and any\n * other layout container an application registers should be too — a different arrangement of the same regions,\n * or, later, an alternative rendering that draws decoration around them.\n *\n * A layout preset uses them like this:\n *\n * ```tsx\n * const layout = useAppShellLayout();\n * const hasBeenReady = useAppShellFirstReady(layout.isLayoutReady);\n * if (!layout.isLayoutReady && !hasBeenReady) return <AppShellLoadingState />;\n * return (\n *   <AppShellProviders layout={layout}>\n *     <div className=\"my-arrangement\">\n *       <AppShellRegionOutlet region={ShellRegion.SIDEBAR} placement={HorizontalPlacement.START} />\n *       <AppShellRegionOutlet region={ShellRegion.MENUBAR} />\n *       <AppShellContentOutlet className=\"flex-1 relative min-w-0\">{children}</AppShellContentOutlet>\n *       <AppShellOverlaysOutlet />\n *     </div>\n *   </AppShellProviders>\n * );\n * ```\n *\n * Four rules keep a custom layout correct:\n *\n * - **Render `AppShellProviders` exactly once, around the whole shell.** It owns the single open state and the\n *   single hotkey registration of the command menu, notification center and quick switcher; two copies would\n *   make one shortcut open two dialogs.\n * - **Place every region the application configures.** An outlet renders nothing when its region is not\n *   configured, so placing an outlet is always safe; leaving one out silently drops a region.\n * - **Render `AppShellContentOutlet` exactly once.** It is the `<main>` landmark, and overlays portal into it —\n *   unless the layout also renders `AppShellOverlayPortalLayer`, which then takes the overlays instead. A layout that\n *   transforms its regions (a 3D placement) must render that layer OUTSIDE the transformed subtree: a transformed\n *   ancestor is the containing block of every `position: fixed` descendant, so a dialog in `<main>` would be confined\n *   to the pane and a menu would be placed in the wrong coordinates.\n * - **Give the root `position: relative`, not `isolation: isolate`,** when the theme may declare a background\n *   layer. That layer is painted in its own stacking context above ordinary in-flow content, so shell text with\n *   no positioned ancestor is painted UNDER it; positioning the root lifts the whole shell above it. `isolate`\n *   would also lift it, but would make the shell one stacking context, so an overlay outside the shell with a\n *   lower z-index (a consent prompt) would paint over the shell's own dialogs.\n */\n\n/** The layout decisions `useAppShellLayout()` computed, shared with every outlet below the providers. */\nconst AppShellLayoutContext = createContext<AppShellLayoutInfo | null>(null);\n\n/** Lets the content outlet hand its `<main>` element to the providers, which expose it as the portal container. */\nconst AppShellPortalTargetContext = createContext<((node: HTMLElement | null) => void) | null>(null);\n\n/** Lets `AppShellOverlayPortalLayer` hand its element to the providers, which then prefer it over `<main>`. */\nconst AppShellOverlayLayerTargetContext = createContext<((node: HTMLElement | null) => void) | null>(null);\n\nfunction useAppShellLayoutContext(consumer: string): AppShellLayoutInfo {\n  const layout = useContext(AppShellLayoutContext);\n  if (!layout) {\n    throw new Error(`${consumer} must be rendered inside <AppShellProviders>, which supplies the layout it places regions from.`);\n  }\n  return layout;\n}\n\n/**\n * Latches the FIRST time the shell becomes ready.\n *\n * `isLayoutReady` derives from configuration presence and can drop transiently after bootstrap (an\n * organization switch reloading config, for example). Replacing the mounted shell with a loading state on such\n * a drop would unmount every provider and zone below it and destroy navigation state — the failure mode\n * `AppLoadingGate` documents. So a layout shows its loading state only while this returns `false`.\n */\nexport function useAppShellFirstReady(isLayoutReady: boolean): boolean {\n  const [hasLayoutBeenReady, setHasLayoutBeenReady] = useState(false);\n  useEffect(() => {\n    if (isLayoutReady) setHasLayoutBeenReady(true);\n  }, [isLayoutReady]);\n  return hasLayoutBeenReady;\n}\n\n/**\n * The shell's loading state: a centred spinner on the page background, announced politely. What every layout\n * shows while `useAppShellFirstReady` says the shell has never been ready — one component rather than a copy per\n * layout, so the loading state is the same whatever the disposal.\n */\nexport function AppShellLoadingState(): React.JSX.Element {\n  return (\n    <Surface asChild emitPolicyVars={false} variant={SurfaceVariant.SHELL} policyOverride={NON_CANONICAL_SHELL_SURFACE_POLICY_OVERRIDE}>\n      <div className=\"h-screen w-screen bg-background flex items-center justify-center\" role=\"status\" aria-live=\"polite\">\n        <div className=\"text-center\">\n          <LoadingSpinner size={32} className=\"text-primary mx-auto mb-field\" aria-hidden=\"true\" />\n        </div>\n      </div>\n    </Surface>\n  );\n}\n\nexport interface AppShellProvidersProps {\n  /** The result of `useAppShellLayout()`, computed once by the layout and shared with every outlet. */\n  layout: AppShellLayoutInfo;\n  children: React.ReactNode;\n}\n\n/**\n * The providers every shell region reads, and nothing else — they render no DOM of their own:\n *\n * - `PortalContainerContext`, holding the `<main>` element `AppShellContentOutlet` registers, so overlays opened\n *   from any region portal into the content area — or, when the layout renders `AppShellOverlayPortalLayer`, that\n *   layer instead;\n * - `HostedComponentInteractionsProvider`, the single owner of the open state and the open hotkey of the\n *   interactive hosted components (command menu, notification center, quick switcher), which may be hosted in the\n *   menubar and the sidebar at once.\n */\nexport function AppShellProviders({ layout, children }: AppShellProvidersProps): React.JSX.Element {\n  const [portalContainer, setPortalContainer] = useState<HTMLElement | null>(null);\n  const [overlayLayer, setOverlayLayer] = useState<HTMLElement | null>(null);\n  const registerPortalTarget = useCallback((node: HTMLElement | null) => {\n    setPortalContainer(node);\n  }, []);\n  const registerOverlayLayer = useCallback((node: HTMLElement | null) => {\n    setOverlayLayer(node);\n  }, []);\n  return (\n    <AppShellLayoutContext.Provider value={layout}>\n      <AppShellPortalTargetContext.Provider value={registerPortalTarget}>\n        <AppShellOverlayLayerTargetContext.Provider value={registerOverlayLayer}>\n          {/* The dedicated overlay layer wins when a layout renders one; otherwise overlays stay in `<main>`. */}\n          <PortalContainerContext.Provider value={overlayLayer ?? portalContainer}>\n            <HostedComponentInteractionsProvider>{children}</HostedComponentInteractionsProvider>\n          </PortalContainerContext.Provider>\n        </AppShellOverlayLayerTargetContext.Provider>\n      </AppShellPortalTargetContext.Provider>\n    </AppShellLayoutContext.Provider>\n  );\n}\n\n/**\n * A dedicated layer every overlay (dialog, sheet, menu, popover, tooltip) portals into, for a layout whose regions\n * are TRANSFORMED — a 3D placement. Render it once, inside the providers but OUTSIDE the transformed subtree; the\n * providers then prefer it to `<main>`. A layout that transforms nothing does not need it.\n *\n * It is a zero-size, untransformed, fixed box at the viewport's origin: an overlay positioned `fixed` resolves\n * against the viewport, one positioned `absolute` against the viewport's origin, so floating content lands where its\n * trigger is on screen. It carries the stacking tier overlays need above a layout's own layers.\n */\nexport function AppShellOverlayPortalLayer(): React.JSX.Element {\n  const register = useContext(AppShellOverlayLayerTargetContext);\n  if (!register) {\n    throw new Error('AppShellOverlayPortalLayer must be rendered inside <AppShellProviders>, which exposes it as the portal container.');\n  }\n  return <div ref={register} data-shell-overlay-layer=\"\" className=\"fixed left-0 top-0 z-50 h-0 w-0\" />;\n}\n\n/**\n * Which region to render, and — for a region that sits at an edge — at which edge. The content area is not\n * among them: it has its own outlet, because it owns `<main>` and the page.\n *\n * `placement` renders the region only when the application configured THAT placement. A layout that places the\n * same region at two positions — as the default layout does for the sidebar's start and end edges — renders one\n * outlet per edge. Omitted, the region renders at whatever placement is configured. The type admits only the\n * placement axis the region has, so a sidebar cannot be asked for a vertical edge and render nothing.\n */\nexport type AppShellRegionOutletProps =\n  | { region: ShellRegion.SIDEBAR | ShellRegion.UTILITY_PANEL; placement?: HorizontalPlacement.START | HorizontalPlacement.END }\n  | { region: ShellRegion.STATUS_BAR; placement?: StatusBarPlacement }\n  | { region: ShellRegion.ACTIVITY_BAR | ShellRegion.MENUBAR | ShellRegion.TOOLBAR; placement?: never };\n\n/**\n * Renders one shell region's component — the registry-resolved wrapper, with its placement prop — when the\n * application configures that region (and, if `placement` is given, at that placement). Renders nothing\n * otherwise, so placing an outlet for every region is always safe.\n */\nexport function AppShellRegionOutlet(props: AppShellRegionOutletProps): React.JSX.Element | null {\n  const layout = useAppShellLayoutContext('AppShellRegionOutlet');\n  const { region, placement } = props;\n  const at = <T extends HorizontalPlacement | VerticalPlacement>(configured: T): T | null =>\n    placement === undefined || placement === configured ? configured : null;\n\n  switch (region) {\n    case ShellRegion.ACTIVITY_BAR:\n      return layout.hasActivityBar ? <ApplicationLevel_ActivityBar /> : null;\n    case ShellRegion.MENUBAR:\n      return layout.hasMenubar ? <ApplicationLevel_MenuBar /> : null;\n    case ShellRegion.TOOLBAR:\n      return layout.hasToolbar ? <ApplicationLevel_Toolbar /> : null;\n    case ShellRegion.SIDEBAR: {\n      const sidebarPlacement = at(layout.sidebarPlacement);\n      return layout.hasSidebar && sidebarPlacement ? <ApplicationLevel_Sidebar placement={sidebarPlacement} /> : null;\n    }\n    case ShellRegion.UTILITY_PANEL: {\n      const utilityPanelPlacement = at(layout.utilityPanelPlacement);\n      return layout.hasUtilityPanel && utilityPanelPlacement ? <ApplicationLevel_UtilityPanel position={utilityPanelPlacement} /> : null;\n    }\n    case ShellRegion.STATUS_BAR: {\n      const statusBarPlacement = at(layout.statusBarPlacement);\n      return layout.hasStatusBar && statusBarPlacement ? <ApplicationLevel_StatusBar placement={statusBarPlacement} /> : null;\n    }\n    default: {\n      const unhandled: never = region;\n      throw new Error(`AppShellRegionOutlet has no rendering for region \"${String(unhandled)}\".`);\n    }\n  }\n}\n\nexport interface AppShellContentOutletProps {\n  /** Classes for the `<main>` element — the layout decides how the content area sizes within its arrangement. */\n  className?: string;\n  /** The route outlet the layout container receives; rendered by the navigation zones while their stack is empty. */\n  children?: React.ReactNode;\n}\n\n/**\n * The content area: the `<main>` landmark carrying `ShellRegion.CONTENT`, the navigation zones, and the floating\n * quick-action button when configured. Its element is registered with `AppShellProviders` as the portal\n * container, so it must be rendered exactly once, inside the providers.\n */\nexport function AppShellContentOutlet({ className, children }: AppShellContentOutletProps): React.JSX.Element {\n  const layout = useAppShellLayoutContext('AppShellContentOutlet');\n  const registerPortalTarget = useContext(AppShellPortalTargetContext);\n  return (\n    <main ref={registerPortalTarget ?? undefined} data-component-area={ShellRegion.CONTENT} className={className}>\n      <NavigationContentAreas routerChildren={children} />\n\n      {/* Floating Quick Action Button */}\n      {layout.hasQuickActionButton && <ApplicationLevel_QuickActionButton placement=\"floating\" />}\n    </main>\n  );\n}\n\n/** The shell's overlay layer: navigation dialogs and sheets, then guidance (tours, tooltips, highlights). */\nexport function AppShellOverlaysOutlet(): React.JSX.Element {\n  return (\n    <>\n      <NavigationOverlays />\n      <GuidanceRenderer />\n    </>\n  );\n}\n/** @wildo_source:part:end saas.frontend.app-shell.building-blocks */\n"]}

package/dist/esm/core/app-shell/PortalContainerContext.d.ts

@@ -10,8 +10,11 @@ export interface PortalTargetResolution {
  * portal their content into the provided container instead of `document.body`.
  *
  * Primary use cases:
- * - Containing overlays within an alternate rendering context (e.g. a Three.js
- *   `<Html>` panel) so they don't escape the spatial container.
+ * - Keeping overlays inside the shell's content area: `AppShellProviders` sets it to the `<main>` element
+ *   `AppShellContentOutlet` registers, for every layout composed from the shell building blocks — or to the
+ *   `AppShellOverlayPortalLayer` a layout that transforms its regions renders outside them. (An earlier
+ *   version of this note named a Three.js `<Html>` panel; that design was rejected because such a panel is a
+ *   separate React root that loses every context — see #1820.)
  * - Scoping overlay z-index stacking to a specific subtree.
  *
  * When `null` (the default), overlays portal to `document.body` — matching the

package/dist/esm/core/app-shell/PortalContainerContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PortalContainerContext.d.ts","sourceRoot":"","sources":["../../../../../src/core/app-shell/PortalContainerContext.tsx"],"names":[],"mappings":"AACA,OAAO,EACL,cAAc,EACd,KAAK,wBAAwB,EAC7B,KAAK,YAAY,EAClB,MAAM,qCAAqC,CAAC;AAG7C,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,WAAW,GAAG,SAAS,CAAC;IACnC,YAAY,EAAE,OAAO,CAAC;CACvB;AAYD;;;;;;;;;;;;;GAaG;AACH,QAAA,MAAM,sBAAsB,sCAA0C,CAAC;AAEvE;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,IAAI,WAAW,GAAG,SAAS,CAG5D;AAED,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,cAAc,EACvB,cAAc,CAAC,EAAE,wBAAwB,GACxC,sBAAsB,CA+CxB;AAED,wBAAgB,iCAAiC,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAelG;AAED,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,cAAc,EACvB,cAAc,CAAC,EAAE,wBAAwB,GACxC,MAAM,CAKR;AAED,OAAO,EAAE,sBAAsB,EAAE,CAAC"}
+{"version":3,"file":"PortalContainerContext.d.ts","sourceRoot":"","sources":["../../../../../src/core/app-shell/PortalContainerContext.tsx"],"names":[],"mappings":"AACA,OAAO,EACL,cAAc,EACd,KAAK,wBAAwB,EAC7B,KAAK,YAAY,EAClB,MAAM,qCAAqC,CAAC;AAG7C,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,WAAW,GAAG,SAAS,CAAC;IACnC,YAAY,EAAE,OAAO,CAAC;CACvB;AAYD;;;;;;;;;;;;;;;;GAgBG;AACH,QAAA,MAAM,sBAAsB,sCAA0C,CAAC;AAEvE;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,IAAI,WAAW,GAAG,SAAS,CAG5D;AAED,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,cAAc,EACvB,cAAc,CAAC,EAAE,wBAAwB,GACxC,sBAAsB,CA+CxB;AAED,wBAAgB,iCAAiC,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAelG;AAED,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,cAAc,EACvB,cAAc,CAAC,EAAE,wBAAwB,GACxC,MAAM,CAKR;AAED,OAAO,EAAE,sBAAsB,EAAE,CAAC"}

package/dist/esm/core/app-shell/PortalContainerContext.js

@@ -14,8 +14,11 @@ function resolveCustomPortalTarget(customPortalTargetId) {
  * portal their content into the provided container instead of `document.body`.
  *
  * Primary use cases:
- * - Containing overlays within an alternate rendering context (e.g. a Three.js
- *   `<Html>` panel) so they don't escape the spatial container.
+ * - Keeping overlays inside the shell's content area: `AppShellProviders` sets it to the `<main>` element
+ *   `AppShellContentOutlet` registers, for every layout composed from the shell building blocks — or to the
+ *   `AppShellOverlayPortalLayer` a layout that transforms its regions renders outside them. (An earlier
+ *   version of this note named a Three.js `<Html>` panel; that design was rejected because such a panel is a
+ *   separate React root that loses every context — see #1820.)
  * - Scoping overlay z-index stacking to a specific subtree.
  *
  * When `null` (the default), overlays portal to `document.body` — matching the

package/dist/esm/core/app-shell/PortalContainerContext.js.map

@@ -1 +1 @@
-{"version":3,"file":"PortalContainerContext.js","sourceRoot":"","sources":["../../../../../src/core/app-shell/PortalContainerContext.tsx"],"names":[],"mappings":"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","sourcesContent":["import { createContext, useContext, useEffect, useLayoutEffect, useState } from 'react';\nimport {\n  SurfaceVariant,\n  type DeepPartialSurfacePolicy,\n  type StackingTier,\n} from '@wildo-ai/presets-components-models';\nimport { useUI } from '~wildo-frontend-lib/core/ui/useUI';\n\nexport interface PortalTargetResolution {\n  container: HTMLElement | undefined;\n  shouldPortal: boolean;\n}\n\nconst useIsomorphicLayoutEffect = typeof window !== 'undefined' ? useLayoutEffect : useEffect;\n\nfunction resolveCustomPortalTarget(customPortalTargetId: string | null): HTMLElement | null {\n  if (!customPortalTargetId || typeof document === 'undefined') {\n    return null;\n  }\n\n  return document.getElementById(customPortalTargetId);\n}\n\n/**\n * Provides a DOM element that Radix UI Portal components should render into.\n *\n * When set, all overlay components (DropdownMenu, Popover, Tooltip, Dialog, etc.)\n * portal their content into the provided container instead of `document.body`.\n *\n * Primary use cases:\n * - Containing overlays within an alternate rendering context (e.g. a Three.js\n *   `<Html>` panel) so they don't escape the spatial container.\n * - Scoping overlay z-index stacking to a specific subtree.\n *\n * When `null` (the default), overlays portal to `document.body` — matching the\n * standard Radix UI behavior.\n */\nconst PortalContainerContext = createContext<HTMLElement | null>(null);\n\n/**\n * Returns the portal container element from the nearest `PortalContainerContext.Provider`,\n * or `undefined` if none is set (which tells Radix to use `document.body`).\n *\n * Preset components call this inside their Portal wrappers:\n * ```tsx\n * const container = usePortalContainer();\n * <DropdownMenuPrimitive.Portal container={container}>\n * ```\n */\nexport function usePortalContainer(): HTMLElement | undefined {\n  const container = useContext(PortalContainerContext);\n  return container ?? undefined;\n}\n\nexport function useSurfacePolicyPortalTarget(\n  variant: SurfaceVariant,\n  policyOverride?: DeepPartialSurfacePolicy,\n): PortalTargetResolution {\n  const appPortalContainer = usePortalContainer();\n  const { getSurfacePolicy } = useUI();\n  const portalTarget = getSurfacePolicy?.(variant, policyOverride)?.stacking?.portalTarget;\n  const customPortalTargetId =\n    typeof portalTarget === 'string' && portalTarget !== 'inline' && portalTarget !== 'app-portal' && portalTarget !== 'reset'\n      ? portalTarget\n      : null;\n  const [customPortalContainer, setCustomPortalContainer] = useState<HTMLElement | null>(() =>\n    resolveCustomPortalTarget(customPortalTargetId),\n  );\n\n  useIsomorphicLayoutEffect(() => {\n    if (!customPortalTargetId || typeof document === 'undefined') {\n      setCustomPortalContainer(null);\n      return;\n    }\n\n    const existingTarget = resolveCustomPortalTarget(customPortalTargetId);\n    setCustomPortalContainer(existingTarget);\n\n    if (existingTarget || typeof MutationObserver === 'undefined') {\n      return;\n    }\n\n    const observer = new MutationObserver(() => {\n      const nextTarget = resolveCustomPortalTarget(customPortalTargetId);\n      if (!nextTarget) return;\n\n      setCustomPortalContainer(nextTarget);\n      observer.disconnect();\n    });\n\n    observer.observe(document.body, { childList: true, subtree: true });\n\n    return () => observer.disconnect();\n  }, [customPortalTargetId]);\n\n  if (portalTarget === 'inline') {\n    return { container: undefined, shouldPortal: false };\n  }\n\n  if (customPortalContainer) {\n    return { container: customPortalContainer, shouldPortal: true };\n  }\n\n  return { container: appPortalContainer, shouldPortal: true };\n}\n\nexport function resolveSurfacePolicyStackingClass(tier: StackingTier | 'reset' | undefined): string {\n  switch (tier) {\n    case 'content':\n      return 'z-(--z-content)';\n    case 'transient':\n      return 'z-(--z-transient)';\n    case 'guidance':\n      return 'z-(--z-guidance)';\n    case 'critical':\n      return 'z-(--z-critical)';\n    case 'overlay':\n    case 'reset':\n    default:\n      return 'z-(--z-overlay)';\n  }\n}\n\nexport function useSurfacePolicyStackingClass(\n  variant: SurfaceVariant,\n  policyOverride?: DeepPartialSurfacePolicy,\n): string {\n  const { getSurfacePolicy } = useUI();\n  const stackingTier = getSurfacePolicy?.(variant, policyOverride)?.stacking?.stackingTier;\n\n  return resolveSurfacePolicyStackingClass(stackingTier);\n}\n\nexport { PortalContainerContext };\n"]}
+{"version":3,"file":"PortalContainerContext.js","sourceRoot":"","sources":["../../../../../src/core/app-shell/PortalContainerContext.tsx"],"names":[],"mappings":"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","sourcesContent":["import { createContext, useContext, useEffect, useLayoutEffect, useState } from 'react';\nimport {\n  SurfaceVariant,\n  type DeepPartialSurfacePolicy,\n  type StackingTier,\n} from '@wildo-ai/presets-components-models';\nimport { useUI } from '~wildo-frontend-lib/core/ui/useUI';\n\nexport interface PortalTargetResolution {\n  container: HTMLElement | undefined;\n  shouldPortal: boolean;\n}\n\nconst useIsomorphicLayoutEffect = typeof window !== 'undefined' ? useLayoutEffect : useEffect;\n\nfunction resolveCustomPortalTarget(customPortalTargetId: string | null): HTMLElement | null {\n  if (!customPortalTargetId || typeof document === 'undefined') {\n    return null;\n  }\n\n  return document.getElementById(customPortalTargetId);\n}\n\n/**\n * Provides a DOM element that Radix UI Portal components should render into.\n *\n * When set, all overlay components (DropdownMenu, Popover, Tooltip, Dialog, etc.)\n * portal their content into the provided container instead of `document.body`.\n *\n * Primary use cases:\n * - Keeping overlays inside the shell's content area: `AppShellProviders` sets it to the `<main>` element\n *   `AppShellContentOutlet` registers, for every layout composed from the shell building blocks — or to the\n *   `AppShellOverlayPortalLayer` a layout that transforms its regions renders outside them. (An earlier\n *   version of this note named a Three.js `<Html>` panel; that design was rejected because such a panel is a\n *   separate React root that loses every context — see #1820.)\n * - Scoping overlay z-index stacking to a specific subtree.\n *\n * When `null` (the default), overlays portal to `document.body` — matching the\n * standard Radix UI behavior.\n */\nconst PortalContainerContext = createContext<HTMLElement | null>(null);\n\n/**\n * Returns the portal container element from the nearest `PortalContainerContext.Provider`,\n * or `undefined` if none is set (which tells Radix to use `document.body`).\n *\n * Preset components call this inside their Portal wrappers:\n * ```tsx\n * const container = usePortalContainer();\n * <DropdownMenuPrimitive.Portal container={container}>\n * ```\n */\nexport function usePortalContainer(): HTMLElement | undefined {\n  const container = useContext(PortalContainerContext);\n  return container ?? undefined;\n}\n\nexport function useSurfacePolicyPortalTarget(\n  variant: SurfaceVariant,\n  policyOverride?: DeepPartialSurfacePolicy,\n): PortalTargetResolution {\n  const appPortalContainer = usePortalContainer();\n  const { getSurfacePolicy } = useUI();\n  const portalTarget = getSurfacePolicy?.(variant, policyOverride)?.stacking?.portalTarget;\n  const customPortalTargetId =\n    typeof portalTarget === 'string' && portalTarget !== 'inline' && portalTarget !== 'app-portal' && portalTarget !== 'reset'\n      ? portalTarget\n      : null;\n  const [customPortalContainer, setCustomPortalContainer] = useState<HTMLElement | null>(() =>\n    resolveCustomPortalTarget(customPortalTargetId),\n  );\n\n  useIsomorphicLayoutEffect(() => {\n    if (!customPortalTargetId || typeof document === 'undefined') {\n      setCustomPortalContainer(null);\n      return;\n    }\n\n    const existingTarget = resolveCustomPortalTarget(customPortalTargetId);\n    setCustomPortalContainer(existingTarget);\n\n    if (existingTarget || typeof MutationObserver === 'undefined') {\n      return;\n    }\n\n    const observer = new MutationObserver(() => {\n      const nextTarget = resolveCustomPortalTarget(customPortalTargetId);\n      if (!nextTarget) return;\n\n      setCustomPortalContainer(nextTarget);\n      observer.disconnect();\n    });\n\n    observer.observe(document.body, { childList: true, subtree: true });\n\n    return () => observer.disconnect();\n  }, [customPortalTargetId]);\n\n  if (portalTarget === 'inline') {\n    return { container: undefined, shouldPortal: false };\n  }\n\n  if (customPortalContainer) {\n    return { container: customPortalContainer, shouldPortal: true };\n  }\n\n  return { container: appPortalContainer, shouldPortal: true };\n}\n\nexport function resolveSurfacePolicyStackingClass(tier: StackingTier | 'reset' | undefined): string {\n  switch (tier) {\n    case 'content':\n      return 'z-(--z-content)';\n    case 'transient':\n      return 'z-(--z-transient)';\n    case 'guidance':\n      return 'z-(--z-guidance)';\n    case 'critical':\n      return 'z-(--z-critical)';\n    case 'overlay':\n    case 'reset':\n    default:\n      return 'z-(--z-overlay)';\n  }\n}\n\nexport function useSurfacePolicyStackingClass(\n  variant: SurfaceVariant,\n  policyOverride?: DeepPartialSurfacePolicy,\n): string {\n  const { getSurfacePolicy } = useUI();\n  const stackingTier = getSurfacePolicy?.(variant, policyOverride)?.stacking?.stackingTier;\n\n  return resolveSurfacePolicyStackingClass(stackingTier);\n}\n\nexport { PortalContainerContext };\n"]}

package/dist/esm/core/app-shell/app-shell.schemas.d.ts

@@ -2,10 +2,10 @@ import type React from 'react';
 import type { UseFormReturn } from 'react-hook-form';
 import type { z } from 'zod';
 import { HorizontalPlacement } from '@wildo-ai/presets-components-models';
+import type { VerticalPlacement } from '@wildo-ai/presets-components-models';
 import type { ForeignKeyDisplayMode, ViewportBreakpoint } from '@wildo-ai/zod-decorators';
 import type { AppScopeFieldDefinition } from '../../core/resources/resources.frontend.schemas';
-import type { ApplicationLevelComponentType, StatusBarItemType } from '../../core/config/app-level-components.frontend.schemas';
-import type { VerticalPlacement } from '@wildo-ai/presets-components-models';
+import type { ApplicationLevelComponentType, StatusBarItemType, StatusBarPlacement } from '../../core/config/app-level-components.frontend.schemas';
 import type { QuickSwitcherFieldPresentation, UserDropdownAvatarDisplay, UserDropdownSection } from '../../core/config/app-configuration-frontend.schemas';
 import type { FrontendComponentType, PlacementSide } from '@wildo-ai/presets-components-models';
 import type { ComponentRegistryRef } from '../../core/components-registry/component-registry.frontend.schemas';
@@ -176,13 +176,11 @@ export interface SidebarConfigObject {
 }
 export declare function isSidebarConfigObject(config: unknown): config is SidebarConfigObject;
 /**
- * Narrowing guard for StatusBar object config.
- * StatusBar config can be `boolean | VerticalPlacement (string) | object`.
- * This guard identifies the object form, distinguishing it from both
- * the boolean and string-shorthand variants.
+ * The object form of the status bar's configuration. The configuration is `boolean | StatusBarPlacement (the
+ * string shorthand) | StatusBarConfigObject`.
  */
 export interface StatusBarConfigObject {
-    placement?: VerticalPlacement;
+    placement?: StatusBarPlacement;
     showMemoryUsage?: boolean;
     showNotificationCount?: boolean;
     showConnectionStatus?: boolean;
@@ -194,6 +192,7 @@ export interface StatusBarConfigObject {
     statusItems?: StatusBarConfigItem[];
     style?: React.CSSProperties;
 }
+/** Narrowing guard for the object form, distinguishing it from the boolean and string-shorthand forms. */
 export declare function isStatusBarConfigObject(config: unknown): config is StatusBarConfigObject;
 export type UtilityPanelPlacement = HorizontalPlacement.START | HorizontalPlacement.END;
 export interface UtilityPanelConfigObject {
@@ -328,8 +327,8 @@ export interface AppShellLayoutInfo {
     hasActivityBar: boolean;
     hasQuickActionButton: boolean;
     hasUtilityPanel: boolean;
-    sidebarPlacement: HorizontalPlacement;
-    statusBarPlacement: VerticalPlacement;
+    sidebarPlacement: HorizontalPlacement.START | HorizontalPlacement.END;
+    statusBarPlacement: StatusBarPlacement;
     utilityPanelPlacement: UtilityPanelPlacement;
     isLayoutReady: boolean;
 }
@@ -804,9 +803,17 @@ export interface MenuUserOrgBehavior {
         _id: string;
         name: string;
     } | undefined;
+    /**
+     * The organizations the person can switch into. `viaProviderOrganizationName` is present only on a CLIENT
+     * organization they work in as a service firm's expert (#1597) — the firm's name, so the switcher can
+     * group clients apart from the person's own organizations and say through whom each is reached. A
+     * client appears only while its relationship is live: the organization read behind this list passes the
+     * per-request live filter, so an ended or paused relationship drops the client from the switcher.
+     */
     organizations: {
         _id: string;
         name: string;
+        viaProviderOrganizationName?: string;
     }[];
     /** Dropdown sections to render. The `SETTINGS` entry opens the unified Settings Hub. */
     sections: UserDropdownSection[];
@@ -843,6 +850,8 @@ export interface MenuBarBehavior {
         group?: string;
         /** Whether this item is the current destination — at most one item is (see `useMenuBarBehavior`). */
         isActive: boolean;
+        /** The badge KEY to draw beside the label (`NavigationItemBadge`), when the declaration names one. */
+        notificationBadgeRef?: string;
         onExecute: () => void;
     }[];
     menubarConfig: {