@godxjp/ui 28.7.0 → 28.9.0

package/dist/props/components/navigation.prop.d.ts

@@ -1,5 +1,7 @@
 /** Navigation component prop types — @see docs/COMPONENTS.md#navigation */
 import type * as React from "react";
+import type { ReactNode } from "react";
+import type { AffixProp } from "./layout.prop.js";
 import type { ActionsProp, ChildrenProp, ClassNameProp, DisabledProp, ErrorProp, HasActiveFiltersProp, IdProp, LabelProp, OnClearFiltersProp, PendingProp, PlaceholderProp, StickyProp, TextAlignProp } from "../vocabulary/index.js";
 import type { SearchSelectOptionProp } from "./data-entry.prop.js";
 /**
@@ -666,3 +668,264 @@ export type ConversationsProp = {
     id?: IdProp;
     className?: ClassNameProp;
 };
+/**
+ * Which pointer action opens a panel. Ant Design `triggerSubMenuAction`, minus antd's third
+ * value: `contextMenu` is a Dropdown affordance, and a right-click that opened a site nav panel
+ * would shadow the browser's own menu.
+ *
+ * `click` is the default here where antd defaults to `hover`, and that is the WCAG 2.2 call, not
+ * a taste one: a hover-only trigger has no equivalent on a touch screen. `hover` remains
+ * available and still accepts click - see `MegaMenuProp.triggerAction`.
+ */
+export type MegaMenuTriggerActionProp = "click" | "hover";
+/** One link inside a panel group. A leaf: it navigates, it never opens anything. */
+export type MegaMenuLinkProp = {
+    /** Stable identity. Ant Design `MenuItemType.key`. */
+    key: string;
+    /** Ant Design `MenuItemType.label`. */
+    label: React.ReactNode;
+    /** Destination. Omit it and the row reports through `onValueChange` instead (SPA visit). */
+    href?: string;
+    /** A line under the label. Ant Design `MenuItemType.extra`, given the shape a nav panel uses. */
+    description?: React.ReactNode;
+    /** Ant Design `MenuItemType.icon`. Decorative - the label is the accessible name. */
+    icon?: React.ReactNode;
+    /** Ant Design `MenuItemType.disabled`. */
+    disabled?: DisabledProp;
+};
+/**
+ * One column of a panel. Ant Design `MenuItemGroupType` (`type: "group"`), which is exactly this:
+ * a labelled cluster of items that is itself not interactive.
+ */
+export type MegaMenuGroupProp = {
+    key: string;
+    /** Ant Design `MenuItemGroupType.label`. Omit for a bare column of links with no heading. */
+    label?: LabelProp;
+    /** A sentence under the group heading. No antd equivalent - antd groups carry a label only. */
+    description?: React.ReactNode;
+    /** Decorative glyph beside the group heading. */
+    icon?: React.ReactNode;
+    /** Ant Design `MenuItemGroupType.children`, narrowed to leaves: a panel is one level deep. */
+    links: readonly MegaMenuLinkProp[];
+};
+/** The disclosure panel behind one top-level item. Ant Design `SubMenuType.children`. */
+export type MegaMenuPanelProp = {
+    /** The columns. Ant Design `SubMenuType.children` restricted to `type: "group"` entries. */
+    groups: readonly MegaMenuGroupProp[];
+    /** A full-width strip below the columns - a promo, a "see all", a support line. */
+    footer?: React.ReactNode;
+};
+/**
+ * One top-level bar item. With a `panel` it is a DISCLOSURE BUTTON (Ant Design `SubMenuType`);
+ * without one it is a plain link (Ant Design `MenuItemType`) - the "Top-Level Links" half of the
+ * APG pattern this implements.
+ */
+export type MegaMenuItemProp = {
+    key: string;
+    label: React.ReactNode;
+    /** Only meaningful without a `panel`: a disclosure button is not a link. */
+    href?: string;
+    icon?: React.ReactNode;
+    disabled?: DisabledProp;
+    panel?: MegaMenuPanelProp;
+};
+/**
+ * Router link component, same contract as `Sidebar.linkComponent`: it receives `href` plus the
+ * row's state props and children, and renders exactly one `<a>`.
+ */
+export type MegaMenuLinkComponentProp = React.ComponentType<React.AnchorHTMLAttributes<HTMLAnchorElement> & {
+    href?: string;
+}>;
+/**
+ * MegaMenu - a primary site navigation whose top-level items disclose a full-width panel of
+ * grouped links.
+ *
+ * Implements WAI-ARIA APG **Disclosure Navigation with Top-Level Links**, NOT Menubar. A site nav
+ * is a set of LINKS to places, not a menu of commands, and `role="menu"` promises assistive
+ * technology a command widget it will then navigate as one. That is the classic megamenu a11y
+ * error, and it is also why this cannot be `DropdownMenu` + a token: `DropdownMenu` is
+ * react-aria-components `Menu`, i.e. `role="menu"` / `role="menuitem"` by construction.
+ */
+export type MegaMenuProp = {
+    /** The bar. Ant Design `items`. */
+    items: readonly MegaMenuItemProp[];
+    /** Key of the open panel, or `null` for none. Ant Design `openKeys`, collapsed to one level. */
+    open?: string | null;
+    /** Initial uncontrolled open panel. Ant Design `defaultOpenKeys`, collapsed to one level. */
+    defaultOpen?: string | null;
+    /** Fires with the newly open panel's key, or `null` when everything closed. Ant `onOpenChange`. */
+    onOpenChange?: (key: string | null) => void;
+    /** Key of the item for the CURRENT ROUTE - renders `aria-current="page"`. Ant `selectedKeys`. */
+    value?: string;
+    /** Uncontrolled initial current route. Ant Design `defaultSelectedKeys`. */
+    defaultValue?: string;
+    /**
+     * Fires with the activated key (a top-level link, or a panel link). Ant Design `onClick`.
+     * Activation always closes the open panel - the "close on route change" half of the contract
+     * that does not need a router.
+     */
+    onValueChange?: (key: string) => void;
+    /** Bar density. The trigger box tracks the matching `--control-height` tier. */
+    size?: "xs" | "sm" | "md" | "lg";
+    /** Ant Design `triggerSubMenuAction`. `hover` also accepts click, so touch is never stranded. */
+    triggerAction?: MegaMenuTriggerActionProp;
+    /** Ant Design `subMenuOpenDelay`, in MILLISECONDS (antd uses seconds). `hover` only. */
+    openDelay?: number;
+    /**
+     * Ant Design `subMenuCloseDelay`, in MILLISECONDS. This is the hover-intent grace period: the
+     * pointer may leave the bar entirely for this long - crossing a diagonal toward the panel -
+     * before anything closes. `hover` only.
+     */
+    closeDelay?: number;
+    /** Accessible name of the `<nav>` landmark. A plain string: it lands on `aria-label`. */
+    label?: string;
+    /** Ant Design `expandIcon`. `false` removes the chevron; a node replaces it. */
+    expandIcon?: React.ReactNode | false;
+    /** Router link component for every `href` in the bar and the panels. */
+    linkComponent?: MegaMenuLinkComponentProp;
+    id?: IdProp;
+    className?: ClassNameProp;
+} & Omit<React.HTMLAttributes<HTMLElement>, "onChange" | "defaultValue" | "children">;
+/**
+ * One entry of `Anchor items` — Ant Design `AnchorItem`, field for field.
+ *
+ * `key` / `href` / `title` / `target` / `children` are antd's, with the same meanings; antd's
+ * per-link `targetOffset` (6.4.0) is here under the logical name the component-level prop uses.
+ * @see Anchor
+ */
+export type AnchorItemProp = {
+    /** Stable identity of the link. Ant Design `AnchorItem.key`. */
+    key: React.Key;
+    /** The in-page fragment this entry points at — `"#pricing"`. Ant Design `AnchorItem.href`. */
+    href: string;
+    /** The link's visible content. Ant Design `AnchorItem.title`. */
+    title: ReactNode;
+    /** `<a target>` — for the rare entry that points off-page. Ant Design `AnchorItem.target`. */
+    target?: string;
+    /**
+     * ONE level of nesting, exactly as Ant Design allows, and — again exactly as Ant Design — it is
+     * DROPPED when `direction="horizontal"`, where a nested list has nowhere to go. A horizontal
+     * anchor carrying `children` warns in development rather than rendering a second row.
+     */
+    children?: AnchorItemProp[];
+    /**
+     * Replace this entry's `href` in history instead of pushing it. Ant Design `AnchorItem.replace`,
+     * default `false`, and it overrides the component-level `replace`.
+     */
+    replace?: boolean;
+    /**
+     * Scroll landing offset for THIS entry, overriding the component's `targetOffsetBlockStart`.
+     * Ant Design `AnchorItem.targetOffset` (6.4.0), renamed to its logical axis for the reason
+     * `AffixProp.offsetBlockStart` states.
+     */
+    targetOffsetBlockStart?: number;
+};
+/** The scroll box an `Anchor` measures its sections in. Ant Design `AnchorContainer`. @see Anchor */
+export type AnchorContainerProp = HTMLElement | Window;
+/**
+ * `Anchor`'s own layout axis — Ant Design `direction`, and the word `Separator` / `Flex` /
+ * `Toolbar` already use for the same idea here, so antd's spelling and this library's agree.
+ * @see Anchor
+ */
+export type AnchorDirectionProp = "vertical" | "horizontal";
+/**
+ * @see Anchor — Ant Design's `Anchor`: the in-page section navigation, and the thing that COMPUTES
+ * which section is current. `NavList activeId` takes that answer as a prop; nothing else in this
+ * library works it out.
+ *
+ * antd's surface, ported first: `items`, `direction`, `affix`, `bounds`, `getContainer`,
+ * `getCurrentAnchor`, `offsetTop`, `targetOffset`, `showInkInFixed`, `replace`, `onChange`,
+ * `onClick`. Three renames, each written at its field: the two physical offsets take their
+ * logical axis, and antd's `onChange` becomes `onValueChange` because the active href here IS a
+ * controlled value (`value` / `defaultValue` / `onValueChange`), which antd has no spelling for
+ * at all. All three antd names stay findable — declared `never`, `@deprecated` with the
+ * replacement named, and warned about in development.
+ */
+export type AnchorProp = {
+    /** The entries, in document order. Ant Design `items`. */
+    items?: AnchorItemProp[];
+    /** Layout axis. Ant Design `direction`, default `"vertical"`. */
+    direction?: AnchorDirectionProp;
+    /**
+     * Pin the nav with `Affix`. Ant Design `affix`, default `true`, and antd's object form is
+     * literally `AffixProps` minus the three fields `Anchor` supplies itself — which is why gh#827
+     * lands before gh#828.
+     *
+     * `false` leaves the nav in the flow. An object is forwarded to `Affix`; `offsetBlockStart`,
+     * `target` and `children` come from `Anchor` and are not yours to set there.
+     */
+    affix?: boolean | Omit<AffixProp, "offsetBlockStart" | "offsetTop" | "target" | "children">;
+    /** Tolerance, in pixels, added to the decision line. Ant Design `bounds`, default `5`. */
+    bounds?: number;
+    /** The scroll box holding the sections. Ant Design `getContainer`, default `() => window`. */
+    getContainer?: () => AnchorContainerProp;
+    /**
+     * Last word on the highlight, given the one the scroll position resolved. Ant Design
+     * `getCurrentAnchor`, kept because it is antd's own escape hatch and it runs INSIDE the
+     * resolution, with no render round-trip. A controlled `value` outranks it.
+     */
+    getCurrentAnchor?: (activeLink: string) => string;
+    /**
+     * Where the decision line sits, measured from the scrollport's block-start edge, and the
+     * distance `Affix` pins the nav at. Ant Design `offsetTop`, default `0`; renamed to its logical
+     * axis for the reason `AffixProp.offsetBlockStart` states.
+     */
+    offsetBlockStart?: number;
+    /**
+     * Where a CLICKED section lands, measured from the scrollport's block-start edge — the room a
+     * pinned header needs. Ant Design `targetOffset`, which defaults to `offsetTop`; same default
+     * here, against `offsetBlockStart`.
+     *
+     * antd uses `targetOffset` for the decision line too whenever it is a number, and that is
+     * ported: the line a section becomes current at and the line it lands on are the same line, so
+     * a click cannot leave the item it just selected unselected.
+     */
+    targetOffsetBlockStart?: number;
+    /** Draw the ink rail when `affix={false}`. Ant Design `showInkInFixed`, default `false`. */
+    showInkInFixed?: boolean;
+    /** Replace the hash in history instead of pushing it. Ant Design `replace`, default `false`. */
+    replace?: boolean;
+    /** Controlled active `href` (the entry carrying `aria-current="location"`). */
+    value?: string;
+    /** Uncontrolled initial active `href`, before the hash or the scroll position has an opinion. */
+    defaultValue?: string;
+    /**
+     * Fires when the active entry changes — from a click, from the landing hash, and from the
+     * scroll position. Ant Design calls this `onChange`; the pair `value`/`defaultValue` makes this
+     * the setter half of a controlled value, and the triad's name for that here is `onValueChange`.
+     *
+     * antd's own note is ported with it: the callback reports the link the SCROLL POSITION resolved,
+     * not the one `getCurrentAnchor` substituted for it.
+     */
+    onValueChange?: (href: string) => void;
+    /**
+     * NOT A PROP — Ant Design's name for `onValueChange`.
+     *
+     * @deprecated Ant Design spells this `onChange`; in `@godxjp/ui` the active href is a controlled
+     * value, so it is `onValueChange`, beside `value` and `defaultValue`.
+     */
+    onChange?: never;
+    /**
+     * NOT A PROP — Ant Design's name for `offsetBlockStart`.
+     *
+     * @deprecated Ant Design spells this `offsetTop`; in `@godxjp/ui` it is `offsetBlockStart`.
+     */
+    offsetTop?: never;
+    /**
+     * NOT A PROP — Ant Design's name for `targetOffsetBlockStart`.
+     *
+     * @deprecated Ant Design spells this `targetOffset`; in `@godxjp/ui` it is
+     * `targetOffsetBlockStart`.
+     */
+    targetOffset?: never;
+    /** Fires on activation, before the scroll. Ant Design `onClick`. */
+    onClick?: (event: React.MouseEvent<HTMLAnchorElement>, item: AnchorItemProp) => void;
+    /**
+     * Accessible name of the `<nav>` landmark — a plain STRING, because it lands on `aria-label`.
+     * antd has no equivalent and ships an unnamed `<div>`; a page routinely carries a breadcrumb, a
+     * rail and this, so a localized default ("On this page") applies when omitted.
+     */
+    label?: string;
+    id?: IdProp;
+    className?: ClassNameProp;
+};