@aglyn/aglyn 1.0.0-beta.268 → 1.0.0-beta.270

package/src/lib/app-utils/native-nav.d.ts

@@ -0,0 +1,265 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * THE NATIVE APPS' NAVIGATION, AS DATA (AGL-3943).
+ *
+ * One manifest both shells draw (docs/mobile/native-navigation.md): the
+ * sidebar for the whole workspace, the sidebar inside one site, and the two
+ * settings modes (the workspace's, and the site's, which merges the
+ * console's Setup and Admin). Zach chose the site's groups on 2026-10-18:
+ * an Overview row, Starred, Website, Sell, Customers, More, Site settings.
+ *
+ * Every row names:
+ * - the console's word for it (`label`), held to the console by
+ *   `apps/console/specs/native-nav-manifest.spec.ts`, which reads the
+ *   console's own tabs, sections and plugin declarations;
+ * - one icon per idea, an SF Symbol and a Material Symbol;
+ * - the native screen it opens (a plugin's declared screen, a core screen
+ *   spec, a site platform screen or a `shell.*` destination);
+ * - the plugin it belongs to, so it hides when that plugin is off for the
+ *   workspace or the site.
+ *
+ * The core's own rows (Home, Overview, Sites, Pages, Media, the settings
+ * modes) are here; a plugin's rows are its own, in
+ * `libs/plugins/<plugin>/src/lib/native-nav.ts` (`NATIVE_NAV_ROWS`), placed
+ * into a list's group by `order` (docs/PACKAGES.md rule 3: the core never
+ * names a plugin). `generate:native-contracts` assembles the two
+ * (`assembleNativeNav`) into the manifest the apps read,
+ * `ContractValues.nativeNavManifest`.
+ *
+ * NO IMPORTS, on purpose: the native apps read this through the generated
+ * contracts, so it must stay a plain module.
+ */
+/** A list the shells draw. */
+export type NativeNavListId = 'workspace' | 'site' | 'workspaceSettings' | 'siteSettings';
+/** One icon per idea: the same row draws the same picture in both scopes. */
+export interface NativeNavIcon {
+    /** An SF Symbol name. */
+    apple: string;
+    /** A Material Symbol name, as `AglynIcons.named` takes it. */
+    android: string;
+}
+/**
+ * Where a row's console twin lives:
+ * - `orgTab` / `hostTab`: a console tab, by its id (`org-nav-tabs.ts`,
+ *   `host-nav-tabs.ts`);
+ * - `orgPluginTab` / `hostPluginTab`: a plugin's `orgNavItems` / `navItems`
+ *   entry, by its href;
+ * - `orgPluginSection` / `hostPluginSection`: a section of a plugin's hub, as
+ *   `{href}/{sectionId}`;
+ * - `setupSection`: a site's Setup section, by its id (`setup-sections.ts`);
+ * - `hostAdminSection`, `orgSettingsSection`, `teamSection`,
+ *   `billingSection`: a section of those hubs, by its `Route` name;
+ * - `consoleWidget`: a plugin's card, as `{slot}/{widgetId}`;
+ * - `shell`: a place the app's shell owns (Home, Overview's page, the
+ *   settings modes), whose console twin is the page named in `id`;
+ * - `nativeOnly`: a native screen the console has no page for.
+ */
+export type NativeNavConsoleSurface = 'orgTab' | 'hostTab' | 'orgPluginTab' | 'hostPluginTab' | 'orgPluginSection' | 'hostPluginSection' | 'setupSection' | 'hostAdminSection' | 'orgSettingsSection' | 'teamSection' | 'billingSection' | 'consoleWidget' | 'shell' | 'nativeOnly';
+export interface NativeNavConsoleRef {
+    surface: NativeNavConsoleSurface;
+    id: string;
+}
+/** A section inside a row's area, as the console's section rail lists it. */
+export interface NativeNavSection {
+    id: string;
+    label: string;
+    screen: string;
+    params?: Record<string, string>;
+    /** Set only when the section belongs to another plugin than its row's. */
+    pluginId?: string;
+    /** The help docs page for it; its row's, unless the console names its own. */
+    docs?: string;
+    console: NativeNavConsoleRef;
+}
+/** An action the area offers from its title bar (Scan stock, New product). */
+export interface NativeNavAction {
+    id: string;
+    label: string;
+    icon: NativeNavIcon;
+    screen: string;
+    params?: Record<string, string>;
+}
+export interface NativeNavRow {
+    /** The idea's id: the same in every list that shows it (`media`). */
+    id: string;
+    /** The console's word. */
+    label: string;
+    /**
+     * The console's word when the native label is a decision of its own
+     * (Overview for the site's analytics, Zach 2026-10-18).
+     */
+    consoleLabel?: string;
+    icon: NativeNavIcon;
+    /** The native screen the row opens. */
+    screen: string;
+    params?: Record<string, string>;
+    /** The plugin the row belongs to: off for the workspace or site, the row hides. */
+    pluginId?: string;
+    /** Only a site admin sees the row, as only they see the console's Admin tab. */
+    requiresHostAdmin?: boolean;
+    /** A settings row's one line, in the words the screens already use. */
+    description?: string;
+    /** Search words besides the label, so typing "billing" finds Plan. */
+    keywords?: string[];
+    /** Where the row sits in its group, ascending; a plugin's row is placed by it. */
+    order?: number;
+    /**
+     * The help docs page for the place, as the console's own help names it
+     * (its `docsTopic` and `docsAnchor`, or the page's `help` prop): a docs-site
+     * path with its anchor, e.g. `/content-and-data/crm/overview#at-the-organization-level`.
+     * The apps open it in the in-app browser, on the docs origin.
+     */
+    docs?: string;
+    sections?: NativeNavSection[];
+    actions?: NativeNavAction[];
+    console: NativeNavConsoleRef;
+}
+export interface NativeNavGroup {
+    id: string;
+    /** The heading; absent for a group drawn without one. */
+    label?: string;
+    /** Folded at rest unless it holds the screen in use, remembered per device. */
+    foldable: boolean;
+    /** `starred`: the person's starred items for this scope, drawn by the shell. */
+    dynamic?: 'starred';
+    rows: NativeNavRow[];
+}
+export interface NativeNavList {
+    id: NativeNavListId;
+    /** The settings mode's title, after its owner's name ("Juniper Street Co. settings"). */
+    title?: string;
+    groups: NativeNavGroup[];
+}
+/** A console place no row holds, and where the apps put it instead. */
+export interface NativeNavElsewhere {
+    console: NativeNavConsoleRef;
+    where: string;
+}
+/** A plugin's row, and the list and group it goes in. */
+export interface NativeNavContribution {
+    list: NativeNavListId;
+    /** A group of that list, by id. */
+    group: string;
+    row: NativeNavRow;
+}
+/** Where the Create new menu is offered: the whole workspace, or one site. */
+export type NativeNavCreateScope = 'workspace' | 'site';
+/**
+ * One item of the Create new menu ("+" on the rail, the center tab on
+ * phones): what the console offers to create from that scope, opening the
+ * area's own create form.
+ */
+export interface NativeNavCreateItem {
+    id: string;
+    /** The thing made, in the console's words ("Draft order", "Service"). */
+    label: string;
+    icon: NativeNavIcon;
+    /** The native screen the item opens, with `params` that open its create form. */
+    screen: string;
+    params?: Record<string, string>;
+    /** The plugin it belongs to: off for the workspace or site, the item is not offered. */
+    pluginId?: string;
+    /** Only a site admin is offered it. */
+    requiresHostAdmin?: boolean;
+    /** The workspace permission the console's create action asks for (`hosts.create`, `data.manage`). */
+    permission?: string;
+    /** The site roles that may make it, as the rules hold them (`canWriteHostContent`). */
+    hostRoles?: string[];
+    /** The plan feature it needs; without it the item is shown blocked, with `blockedReason`. */
+    planFeature?: string;
+    /** Why it is blocked when the plan lacks `planFeature`; the default reason otherwise. */
+    blockedReason?: string;
+    /** Where it sits in the menu, ascending. */
+    order?: number;
+    /** Where the console offers the same create action. */
+    console: NativeNavConsoleRef;
+}
+/** One scope's Create new menu. */
+export interface NativeNavCreateList {
+    scope: NativeNavCreateScope;
+    items: NativeNavCreateItem[];
+}
+/** A plugin's Create new item, and the scope that offers it. */
+export interface NativeNavCreateContribution {
+    scope: NativeNavCreateScope;
+    item: NativeNavCreateItem;
+}
+export interface NativeNavManifest {
+    lists: NativeNavList[];
+    /** The Create new menu per scope (AGL-3943). */
+    create?: NativeNavCreateList[];
+    /** Destinations the shells own, which no plugin registers. */
+    shellScreens: string[];
+    elsewhere: NativeNavElsewhere[];
+}
+/** The shells' own destinations. */
+export declare const NATIVE_NAV_SHELL_SCREENS: readonly string[];
+/** An icon pair, for the rows here and in the plugins. */
+export declare const nativeNavIcon: (apple: string, android: string) => NativeNavIcon;
+/** A console reference, for the rows here and in the plugins. */
+export declare const nativeNavRef: (surface: NativeNavConsoleSurface, id: string) => NativeNavConsoleRef;
+/** A section of a plugin hub, at the scope its row stands in. */
+export declare function nativeNavHubSection(scope: 'org' | 'host', href: string, id: string, label: string, screen: string, extra?: Partial<Pick<NativeNavSection, 'params' | 'pluginId'>>): NativeNavSection;
+/**
+ * The core's half of the manifest: every list and group, and the core's own
+ * rows. The manifest the apps read (`ContractValues.nativeNavManifest`) is
+ * this with each plugin's `NATIVE_NAV_ROWS` placed by `assembleNativeNav`.
+ */
+export declare const NATIVE_NAV_MANIFEST: NativeNavManifest;
+/**
+ * The manifest with the plugins' rows placed: each into its list's group by
+ * `order` (a tie keeps the core's row first, then registration order). A row
+ * naming a list or group the core does not have is refused by name, so a
+ * plugin cannot quietly invent a group.
+ */
+export declare function assembleNativeNav(core: NativeNavManifest, contributions: readonly NativeNavContribution[], elsewhere?: readonly NativeNavElsewhere[], creates?: readonly NativeNavCreateContribution[]): NativeNavManifest;
+/** What a Create new item that cannot be used says, when its own reason does not apply. */
+export declare const NATIVE_CREATE_PERMISSION_REASON = "Your role can't create this here. Ask an owner or admin of the workspace.";
+export declare const NATIVE_CREATE_SITE_ROLE_REASON = "Your role on this site can't create this. Ask a site admin.";
+export declare const NATIVE_CREATE_PLAN_REASON = "Your plan doesn't include this. See the plans in Billing.";
+/** A Create new item as one scope offers it. */
+export interface ResolvedCreateItem extends NativeNavCreateItem {
+    /** Shown, but disabled with `reason`: a prerequisite stands between the person and it. */
+    blocked: boolean;
+    reason?: string;
+}
+/**
+ * The Create new menu for the workspace or site in hand. An item of a plugin
+ * that is off is not offered, nor an admin-only item to a non-admin. One the
+ * person may not use is SHOWN, disabled with its reason (prerequisites are
+ * shown, never hidden): a permission or site role they lack, then a plan
+ * feature the workspace lacks. `permissions` and `features` are the
+ * workspace's resolved answers (an absent key is not held); `hostRole` is
+ * the person's role on the site, null at the workspace.
+ */
+export declare function resolveCreateList(manifest: NativeNavManifest, scope: NativeNavCreateScope, enabledPluginIds: readonly string[], permissions: Readonly<Record<string, boolean>>, features: Readonly<Record<string, boolean>>, hostRole: string | null): ResolvedCreateItem[];
+/** A list as one scope shows it: rows for plugins that are off, or admin rows for a non-admin, left out. */
+export interface ResolvedNavList {
+    id: NativeNavListId;
+    title?: string;
+    groups: NativeNavGroup[];
+}
+/**
+ * One list for the workspace or site in hand, from the assembled manifest
+ * (`ContractValues.nativeNavManifest`). `enabledPluginIds` is the site's
+ * effective set (`resolveHostEnabledPlugins`) in site scope and the
+ * workspace's (`resolveEnabledPlugins`) otherwise. A section of another
+ * plugin than its row's hides with that plugin. A group left with no rows is
+ * dropped, except the starred group, which the shell fills.
+ */
+export declare function resolveNavList(manifest: NativeNavManifest, listId: NativeNavListId, enabledPluginIds: readonly string[], hostAdmin: boolean): ResolvedNavList;