@aglyn/plugins-mui 1.0.0-beta.143

package/src/lib/components/tabs.d.ts

@@ -0,0 +1,288 @@
+/**
+ * @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.
+ */
+import * as Aglyn from '@aglyn/aglyn';
+import type { SxProps } from '@mui/material/styles';
+import { type ReactNode } from 'react';
+export declare const TABS_ID: Aglyn.ComponentId;
+export declare const TAB_PANEL_ID: Aglyn.ComponentId;
+/**
+ * How many tabs in a strip can carry a screen link (AGL-1312). The strip is
+ * authored as a free-form label list, so the links have to be flat props —
+ * one per position — and a flat prop needs a name that exists up front.
+ *
+ * Eight is well past any usable navigation row (the marketing content-tabs
+ * row is three) and costs nothing at render: the attributes panel only shows
+ * a link picker for a tab that actually exists, so a two-tab strip shows two.
+ */
+export declare const TAB_LINK_SLOTS = 8;
+/** Prop name carrying the link of the 1-based `position`-th tab. */
+export declare function tabLinkProp(position: number): string;
+/**
+ * The per-tab screen links, `tabLink1`…`tabLink8`. Declared as a mapped type
+ * rather than an index signature: an index signature on the props interface
+ * would force `sx`, `children` and the rest to conform to it.
+ */
+export type TabLinkProps = Partial<Record<'tabLink1' | 'tabLink2' | 'tabLink3' | 'tabLink4' | 'tabLink5' | 'tabLink6' | 'tabLink7' | 'tabLink8', string>>;
+export interface TabsElementProps extends TabLinkProps {
+    /** Tab labels, one per line (commas also accepted). */
+    labels?: string;
+    /**
+     * The LABEL of the tab the strip opens on (AGL-3164). Unset opens the
+     * first tab, which is what every Tabs already in the wild does.
+     *
+     * A label rather than a position, because a position is a silent lie the
+     * moment the list is edited: it keeps pointing at "the second tab" after
+     * the author reorders or renames, and nothing on screen says the wrong
+     * panel is now the one that opens. A label that no longer exists simply
+     * does not match, and the strip falls back to the first tab.
+     *
+     * See {@link openingTabIndex} for the whole rule, and `deferLazyPanelNodes`
+     * in tenant-runtime for the server side of it — the two must agree or the
+     * page ships the wrong panel's markup.
+     */
+    opensOn?: string;
+    /** Accessible name of the strip; also names the nav landmark in link mode. */
+    ariaLabel?: string;
+    orientation?: 'horizontal' | 'vertical';
+    variant?: 'standard' | 'scrollable' | 'fullWidth';
+    /** Centres a standard strip; MUI ignores it when scrollable. */
+    centered?: boolean;
+    textColor?: 'primary' | 'secondary' | 'inherit';
+    indicatorColor?: 'primary' | 'secondary';
+    /**
+     * Render every panel into the SSR output up front instead of building each
+     * panel the first time its tab is opened (AGL-1283 option 3).
+     *
+     * Mount-on-first-selection is the DEFAULT: `/pricing` shipped eight copies
+     * of a 50-row table so desktop visitors could see none of them, and any
+     * large tab set pays the same tax silently. The trade is that an unopened
+     * panel's content is then not in the page source — not indexable, not
+     * findable — so this switch exists for the panels where that matters:
+     * content that appears nowhere else on the page and must reach crawlers.
+     */
+    ssrPanels?: boolean;
+    /**
+     * Legacy opt-in from when eager panels were the default (AGL-1283).
+     * Lazy mounting is now the default, so this is accepted from existing
+     * documents but no longer consulted — `ssrPanels` is the one switch.
+     * Still destructured so an authored value never leaks onto the DOM.
+     */
+    lazyPanels?: boolean;
+    /**
+     * Authored node styles, handed over by the renderer rather than typed into
+     * an attribute — the merge below reads it, so it belongs on the public
+     * interface. Leaving it undeclared (AGL-1284 added the reads, not the
+     * declaration) meant no typed caller could pass one, including the specs
+     * that exist to prove an authored `sx` survives (AGL-1323).
+     */
+    sx?: SxProps;
+    children?: ReactNode;
+}
+export interface TabPanelElementProps {
+    /** Which tab reveals this panel; must match one of the Tabs labels. */
+    label?: string;
+    /**
+     * Set by the server when this panel's children were withheld from the page
+     * payload (AGL-1285, `deferLazyPanelNodes`) — never authored, and there is
+     * deliberately no attribute for it.
+     *
+     * It must be destructured off the prop bag either way: everything else on
+     * this element is spread straight onto a `Box`, so leaving it in produced a
+     * React "does not recognize the prop" warning for every deferred panel.
+     *
+     * It also drives the loading state. A withheld panel that the reader has
+     * just opened has no children yet and is indistinguishable from a panel that
+     * is genuinely empty, and the fetch behind it is a full server compose —
+     * 3.8s cold when measured. This flag is what lets the panel say so.
+     *
+     * It clears itself: the patch from `/api/screen/nodes` carries the ORIGINAL
+     * panel nodes, which never had the marker, so the moment the real children
+     * arrive this is gone and the placeholder with it (AGL-1287).
+     */
+    aglynDeferred?: boolean;
+    /** Authored node styles, merged over the panel's own — see Tabs' `sx`. */
+    sx?: SxProps;
+    children?: ReactNode;
+}
+/**
+ * Splits the authored label list. Newline-separated is the documented
+ * form; commas are accepted because a one-line "A, B, C" is what people
+ * type first.
+ */
+export declare function parseLabels(value: unknown): string[];
+/** Stable DOM id fragment for the tab ⇄ panel aria wiring. */
+export declare function labelSlug(label: string): string;
+/** Case/whitespace-insensitive: authors don't retype labels exactly. */
+export declare function labelsMatch(a: unknown, b: unknown): boolean;
+/**
+ * Which tab the strip opens on, by index into the parsed label list.
+ *
+ * Two rules, in order:
+ *
+ * 1. the tab the author NAMED in `opensOn` (AGL-3164), matched by label with
+ *    the same case/whitespace tolerance panels are matched with;
+ * 2. otherwise the landing tab — the first one WITHOUT a screen link, which
+ *    is how a navigation row says "this is the page you are on" (AGL-1312),
+ *    and which is tab 0 on a strip with no links at all, i.e. exactly what
+ *    this element did before the attribute existed.
+ *
+ * The named tab is refused when it carries a screen link: a linked tab
+ * navigates instead of revealing a panel (AGL-1312), so it is not a tab the
+ * strip can rest on, and opening on it would show the indicator over a panel
+ * nobody can see. It falls back rather than rendering nothing.
+ *
+ * Never returns -1. `landing` is -1 when EVERY tab navigates — the strip
+ * shows no indicator there, but callers still read a label with this index.
+ */
+export declare function openingTabIndex(labels: readonly string[], opensOn?: unknown, linkIds?: readonly (string | undefined)[]): number;
+interface TabsContextValue {
+    activeLabel: string;
+    /** True on the besigner canvas, where every panel is shown at once. */
+    showAll: boolean;
+    /** Panels render nothing until first selected (AGL-1283). */
+    lazyPanels: boolean;
+    /** Labels opened at least once — a lazily mounted panel stays mounted. */
+    opened: ReadonlySet<string>;
+    /**
+     * True when at least one tab carries a screen link (AGL-1312), which makes
+     * the whole row navigation rather than a tab list — see the a11y note on
+     * `TabsElement`. Panels drop `role="tabpanel"` in that mode: a tabpanel
+     * with no tablist to belong to is orphaned ARIA.
+     */
+    navMode: boolean;
+}
+export declare const TabsContext: import("react").Context<TabsContextValue>;
+/**
+ * Tabs (https://mui.com/material-ui/react-tabs/).
+ *
+ * The strip is authored on the container as a label list, and each Tab
+ * Panel child names the label it belongs to. It does **not** slice its
+ * React children by index: the node renderer hands every component a
+ * single `Branch` fragment rather than one element per child node
+ * (`libs/aglyn-node-renderer`), so an index-based split would silently
+ * put all the content behind the first tab. Matching by label also
+ * survives reordering panels in the hierarchy.
+ *
+ * The strip renders from the author's own list, so it is complete in the
+ * SSR output — no registration pass, no empty-then-filled flash, and it
+ * still reads as a tab list with JavaScript disabled.
+ *
+ * ## Link mode (AGL-1312)
+ *
+ * Any tab may carry a screen link (`tabLink1`…`tabLink8`, by position). A
+ * tab that has one renders as a real anchor — navigable, crawlable,
+ * middle-clickable — because the row it exists for (Blog | Changelog |
+ * Newsroom) is navigation ACROSS screens, which a panel switcher can only
+ * fake with empty panels or a hand-styled row of buttons. The anchor is an
+ * `AppLink`, never a bare `href`: a raw href full-reloads the SPA.
+ *
+ * A tab WITHOUT a link keeps today's behavior exactly, and mixed rows work
+ * — the marketing pattern IS a mixed row, since the tab for the page you
+ * are already on must not link to itself. That unlinked tab is also how the
+ * author says which page this copy of the row is on: the strip lands on it,
+ * so the same three-tab row placed on three screens shows the indicator in
+ * the right place on each, with no "selected tab" attribute to keep in sync
+ * — `opensOn` below is for panel rows and gives way to this one.
+ *
+ * ## Which tab opens (AGL-3164)
+ *
+ * `opensOn` names it, by LABEL. Unset opens the first tab, which is what
+ * every Tabs authored before the attribute existed does; a label that no
+ * longer matches opens the first tab too, rather than nothing. The rule
+ * lives in {@link openingTabIndex} and is mirrored server-side by
+ * `deferLazyPanelNodes` (tenant-runtime), which decides which panel's nodes
+ * reach the page at all — so the tab that opens is the one that was
+ * rendered, and the page does not paint one panel and swap to another.
+ *
+ * **Accessibility.** The row is a `tablist` only while NOTHING in it
+ * navigates. As soon as one tab carries a link the whole strip is marked up
+ * as navigation: a `nav` landmark, no `role="tab"`, no `aria-selected`, and
+ * no roving tab stop (every link is its own tab stop, as in any nav). The
+ * alternative — an `<a href>` wearing `role="tab"` — tells assistive tech
+ * the activation will reveal a panel when it actually loads a page, and a
+ * tablist whose children are not tabs is invalid either way. The tab for
+ * the current screen is marked `aria-current="page"`; tabs that still
+ * switch panels stay buttons and keep their `aria-controls`, which is an
+ * accurate disclosure relationship on its own. The half-applied version of
+ * this — links inside a tablist, or panels still claiming `role="tabpanel"`
+ * with no tablist above them — is what this deliberately avoids.
+ */
+declare const TabsElement: import("react").ForwardRefExoticComponent<TabsElementProps & import("react").RefAttributes<HTMLDivElement>>;
+/**
+ * One tab's content. Outside a Tabs container it renders plainly rather
+ * than disappearing — a panel dragged out of its tabs would otherwise
+ * vanish from the canvas with no explanation.
+ */
+export declare const TabPanelElement: import("react").ForwardRefExoticComponent<TabPanelElementProps & import("react").RefAttributes<HTMLDivElement>>;
+/**
+ * Shows a per-tab link picker only once the label list has that many tabs,
+ * so a three-tab strip offers three pickers rather than eight.
+ *
+ * Expressed as a serialisable `pattern` rather than an `is` predicate:
+ * conditions travel with the component schema, and a function in there is a
+ * live grenade the day a schema is cloned or sent across a boundary. An
+ * "item" is a run without a separator that holds something visible, and a
+ * separator run swallows blank lines, so it counts exactly what
+ * `parseLabels` counts.
+ */
+export declare function atLeastLabels(count: number): Record<string, unknown>;
+/**
+ * The "Opens on" field's `resolveProps`: its answers are the element's OWN
+ * tab labels, read from the sibling `labels` field as they are typed
+ * (AGL-3164).
+ *
+ * A picker rather than a typed index or a typed label. An index goes on
+ * meaning "the second tab" after a reorder, with nothing on screen to say
+ * the wrong panel now opens; a typed label breaks on a rename and on every
+ * typo in between. Choosing from the list the author has just written is the
+ * only form of this control someone who does not write code can get right,
+ * which is the whole reason it exists instead of the tabs being reordered by
+ * hand to obtain a behavior.
+ *
+ * The answers follow the label list as it is edited because the field's
+ * `condition` names `labels`: data-driven-forms subscribes a conditional
+ * field to its condition's trigger fields, and that subscription is what
+ * re-runs this.
+ *
+ * A stored label the list no longer holds is offered back as its own option,
+ * named as gone. The element itself already falls back to the first tab, so
+ * the page is never broken by one; but a picker that rendered BLANK would
+ * read as "not set", and the author would never learn that the choice they
+ * made has stopped being honoured — the same reason a Screen picker names a
+ * target the host no longer has (AGL-1893).
+ */
+export declare function opensOnFieldProps(_props: unknown, field: {
+    input?: {
+        value?: unknown;
+    };
+}, formOptions?: {
+    getFieldState?: (name: string) => {
+        value?: unknown;
+    } | undefined;
+    getState?: () => {
+        values?: Record<string, unknown>;
+    } | undefined;
+}): {
+    options: {
+        value: string;
+        label: string;
+    }[];
+};
+export declare const tabsSchema: Aglyn.ComponentSchema<TabsElementProps>;
+export declare const tabPanelSchema: Aglyn.ComponentSchema<TabPanelElementProps>;
+export declare const tabsPresets: Aglyn.PresetSchema[];
+export default TabsElement;