@ex-grid/pivot-react 0.0.0-stage → 0.2.0-rc.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AkiraMisawa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,43 @@
-# Temporary Holding Version
+# @ex-grid/pivot-react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+ExPivot for React: the Framework Adapter of ExPivot's Script Core, which mounts Excel's PivotTable, drawn by ExGrid, in a React tree.
+
+It is one of the packages of the ExGrid family: Excel-like grids, sheets, pivot tables and charts for reading
+money and risk numbers, published to npm under `@ex-grid` and to NuGet for Blazor, at one shared version.
+
+## Install
+
+```sh
+npm install @ex-grid/pivot-react react react-dom
+```
+
+`react` and `react-dom` are peer dependencies: your application provides them, at the versions `package.json` names.
+
+It depends on exactly the version of `@ex-grid/pivot` and `@ex-grid/react` it was built with, so upgrade the family's packages together.
+
+What it draws reads these stylesheets. Import them once in your application:
+
+```ts
+import '@ex-grid/core/styles.css';
+import '@ex-grid/pivot/styles.css';
+```
+
+## Documentation
+
+[ExPivot on the documentation site](https://akiramisawa.github.io/ex-grid/expivot), read for React with the switch at the top, and every
+version's [Release Notes](https://akiramisawa.github.io/ex-grid/release-notes).
+
+> **The API may still change.** While the version is `0.x`, it may change from one version to the next; each
+> version's Release Notes say what changed. A prerelease, a version with a suffix such as `-rc.1`, passed every
+> test layer in CI on the commit it was built from. A version without a suffix is published only once the
+> project's [Definition of Done](https://github.com/AkiraMisawa/ex-grid/blob/main/docs/definition-of-done.md) is
+> signed off on it.
+
+## Requirements
+
+- **Chrome or Edge.** They are the supported browsers; Safari and Firefox are out of scope.
+- **React 19.0.0 or a later 19.x.**
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,167 @@
+/**
+ * ExPivot for React: the Framework Adapter of ExPivot's Script Core (ADR-0370). `ExPivot` renders the element
+ * the pivot draws into and hands it its props; everything the pivot shows and decides is the Script Core's.
+ *
+ * @packageDocumentation
+ */
+
+import { ChromeMountsMade } from '@ex-grid/react';
+import { ExGridChrome } from '@ex-grid/react';
+import { GridPortals } from '@ex-grid/react';
+import type { PivotChrome } from '@ex-grid/pivot';
+import type { PivotDetailsDialogSlotContext } from '@ex-grid/pivot';
+import type { PivotDetailsTabsSlotContext } from '@ex-grid/pivot';
+import type { PivotFieldListSlotContext } from '@ex-grid/pivot';
+import type { PivotFieldSettingsSlotContext } from '@ex-grid/pivot';
+import type { PivotItemFilterSlotContext } from '@ex-grid/pivot';
+import type { PivotMenuSlotContext } from '@ex-grid/pivot';
+import type { PivotMenuView } from '@ex-grid/pivot';
+import type { PivotPanelSlotContext } from '@ex-grid/pivot';
+import type { PivotReportFiltersSlotContext } from '@ex-grid/pivot';
+import type { PivotStaleReportSlotContext } from '@ex-grid/pivot';
+import type { PivotStandingSlotContext } from '@ex-grid/pivot';
+import type { PivotToolbarSlotContext } from '@ex-grid/pivot';
+import type { PivotValueFieldSettingsSlotContext } from '@ex-grid/pivot';
+import { PivotViewOptions } from '@ex-grid/pivot';
+import { ReactElement } from 'react';
+import { ReactNode } from 'react';
+
+/**
+ * Excel's PivotTable, drawn by ExGrid, beside its Field List. The element it renders is the pivot's root,
+ * which the Script Core owns; every render hands the core the props again, and what did not change asks
+ * nothing again.
+ */
+export declare function ExPivot(props: ExPivotProps): ReactElement;
+
+/**
+ * The Chrome slots an ExPivot takes, each a render function of what the pivot hands that slot (ADR-0390 section 3),
+ * and `grid`, ExGrid's own, which dresses the report's grid and Show Details' grids. A slot not given is drawn by the
+ * built-in markup. A render function is read when its part opens; its answer is rendered as a component of its own,
+ * so it may hold state, kept while the part stands, and a hook belongs in a component it renders.
+ */
+export declare interface ExPivotChrome {
+    /** ExGrid's Chrome for the report's grid and Show Details' grids; the Context Menu's commands are worded by the
+     * pivot. */
+    readonly grid?: ExGridChrome<unknown>;
+    /** A placed field's menu and the Layout menu, drawn with {@link usePivotMenu}. */
+    readonly menu?: (context: PivotMenuSlotContext) => ReactNode;
+    /** Filter…, drawn with {@link usePivotPanel}. */
+    readonly itemFilter?: (context: PivotItemFilterSlotContext) => ReactNode;
+    /** Field Settings…, drawn with {@link usePivotPanel}. */
+    readonly fieldSettings?: (context: PivotFieldSettingsSlotContext) => ReactNode;
+    /** Value Field Settings…, drawn with {@link usePivotPanel}. */
+    readonly valueFieldSettings?: (context: PivotValueFieldSettingsSlotContext) => ReactNode;
+    /** The Pivot Toolbar, drawn with {@link usePivotPart}. */
+    readonly toolbar?: (context: PivotToolbarSlotContext) => ReactNode;
+    /** The report filter band, drawn with {@link usePivotPart}. */
+    readonly reportFilters?: (context: PivotReportFiltersSlotContext) => ReactNode;
+    /** The Stale Report's notice, drawn with {@link usePivotPart}. */
+    readonly staleReport?: (context: PivotStaleReportSlotContext) => ReactNode;
+    /** The Field List, drawn with {@link usePivotPart}. */
+    readonly fieldList?: (context: PivotFieldListSlotContext) => ReactNode;
+    /** The sheet tabs at the report's foot, while Show Details' records stand in a tab, drawn with {@link usePivotPart}. */
+    readonly detailsTabs?: (context: PivotDetailsTabsSlotContext) => ReactNode;
+    /** What the Show Details dialog draws inside the pivot's frame, drawn with {@link usePivotPart}. */
+    readonly detailsDialog?: (context: PivotDetailsDialogSlotContext) => ReactNode;
+}
+
+/**
+ * An ExPivot's props: the Script Core's options, whole, its `chrome` as render functions. `locale` is the browser's
+ * language where not given, the first of its languages the pivot writes in, read once, the first time the pivot is
+ * given none (ADR-0370 section 10); the core never reads it on its own.
+ */
+export declare type ExPivotProps = Omit<PivotViewOptions, 'chrome'> & {
+    /** The parts a Wrapper's Chrome, or the Consumer's own, draws in place of the built-in markup (ADR-0390). */
+    readonly chrome?: ExPivotChrome;
+};
+
+/**
+ * A design-system Wrapper's Chrome with the Consumer's `chrome` over it (ADR-0390): `pivot`, the Wrapper's pivot
+ * slots, and `grid`, its ExGrid Chrome for the report's grid, each slot the Consumer names in its place. A slot given
+ * as `undefined` leaves the Wrapper's, as one not named does. The grid's Chrome is the Wrapper's own object while the
+ * Consumer names none of its slots, so a Chrome handed again with only pivot slots does not dress the report's grid
+ * again. Every Wrapper of ExPivot lays its Chrome so, once per `given`.
+ */
+export declare function layPivotChrome(pivot: Omit<ExPivotChrome, 'grid'>, grid: ExGridChrome<unknown>, given: ExPivotChrome | undefined): ExPivotChrome;
+
+/** The ExPivot's Chrome as the pivot takes it: each slot's render function as a mount function rendering it through
+ * the ExPivot's portals, and `grid`'s as ExGrid for React makes its own. A render function handed again keeps its
+ * mount function. Which slots there are is the pivot's to check; a render function that is not a function is named
+ * here, in React's terms. Exported for the family's Framework Adapters, whose products hand ExPivot's Chrome on to the
+ * pivots they draw, not for a Consumer. */
+export declare function pivotChromeMounts(given: ExPivotChrome | undefined, portals: GridPortals, made: PivotMountsMade): PivotChrome | undefined;
+
+/** What {@link usePivotMenu} hands a menu's contents. */
+export declare interface PivotMenuHandles {
+    /** What the menu shows now: its commands, in the pivot's order, with their group headings. */
+    readonly view: PivotMenuView;
+    /** The props of the command at `index` in the view's commands. */
+    readonly item: (index: number) => PivotMenuItemProps;
+}
+
+/** The props {@link usePivotMenu} hands each command's control: spread them onto it. */
+export declare interface PivotMenuItemProps {
+    /** A choice is a `menuitemradio`, any other command a `menuitem`. */
+    readonly role: 'menuitem' | 'menuitemradio';
+    /** On a choice: whether it is the current one. */
+    readonly 'aria-checked'?: boolean;
+    /** Whether the command cannot run now; a disabled command is shown, never left out. */
+    readonly disabled: boolean;
+    /** Claims the click for the pivot's Input Order (ADR-0240). */
+    readonly 'data-ex-claims': 'click';
+    /** Runs the command the pivot drew last under this one's id. */
+    readonly onClick: () => void;
+    /** On the first enabled command: the one a request for the keyboard is for. */
+    readonly ref?: (control: HTMLElement | null) => void;
+}
+
+/** The mount functions made for an ExPivot's render functions: the pivot's slots', and the grid's. */
+export declare interface PivotMountsMade {
+    /** The pivot's slots' render functions, and the mount function made for each, by slot. */
+    readonly pivot: Map<string, {
+        readonly render: unknown;
+        readonly mount: (slot: HTMLElement, context: unknown) => () => void;
+    }>;
+    /** The report grid's slots', as ExGrid for React makes them. */
+    readonly grid: ChromeMountsMade;
+    /** The report grid's Chrome last handed, and its mount functions. */
+    gridChrome?: {
+        readonly given: unknown;
+        readonly mounts: PivotChrome['grid'];
+    };
+}
+
+/** What {@link usePivotPanel} hands a panel's contents. */
+export declare interface PivotPanelHandles<View> {
+    /** What the panel shows now, drawn again at each change the pivot makes to it. */
+    readonly view: View;
+    /** Takes the panel's first control: the one each request of the pivot's for the keyboard is for. */
+    readonly first: (control: HTMLElement | null) => void;
+}
+
+/**
+ * Draws a menu from its context (ADR-0390 section 3): one control per command, in the pivot's order, a choice as a
+ * `menuitemradio` marked while it is the current one. A press runs the command the pivot drew last under its id, and
+ * the first enabled command takes the keyboard at each request of the pivot's.
+ */
+export declare function usePivotMenu(context: PivotMenuSlotContext): PivotMenuHandles;
+
+/**
+ * Draws one of the pivot's panels from its context (ADR-0390 section 3): Filter…, Field Settings… or Value Field
+ * Settings…. The view is the pivot's draft, read again at each change; each choice goes to the context's setter, and
+ * the hook gives the panel's first control the keyboard at each request, once it is drawn, through the pivot.
+ */
+export declare function usePivotPanel<View>(context: PivotPanelSlotContext & {
+    readonly view: () => View;
+}): PivotPanelHandles<View>;
+
+/**
+ * Draws one of the pivot's standing parts from its context (ADR-0390 section 3): the Pivot Toolbar, the report filter
+ * band, the Stale Report's notice or the Field List. The view is the pivot's, read again at each change; each press goes to the
+ * context's callback, and each control and anchor is handed in by its `ref`, `context.control(name)` and
+ * `context.anchor(name)`, so the pivot gives the keyboard to the control it means and places a popup's frame in its
+ * anchor itself.
+ */
+export declare function usePivotPart<View>(context: PivotStandingSlotContext<View>): View;
+
+export { }

package/dist/index.js

@@ -0,0 +1,160 @@
+// src/ex-pivot.ts
+import { createElement, Fragment, useLayoutEffect as useLayoutEffect2, useMemo, useRef as useRef2, useState as useState2 } from "react";
+import { browserPivotLocale, createPivot } from "@ex-grid/pivot";
+import { useGridPortals } from "@ex-grid/react";
+
+// src/chrome.ts
+import { useLayoutEffect, useRef, useState, useSyncExternalStore } from "react";
+import { chromeMounts } from "@ex-grid/react";
+function laid(under, over) {
+  return { ...under, ...Object.fromEntries(Object.entries(over).filter(([, slot]) => slot !== void 0)) };
+}
+function layPivotChrome(pivot, grid, given) {
+  if (given === void 0) return { ...pivot, grid };
+  const { grid: givenGrid, ...givenPivot } = given;
+  return { ...laid(pivot, givenPivot), grid: givenGrid === void 0 ? grid : laid(grid, givenGrid) };
+}
+var pivotSlots = [
+  "menu",
+  "itemFilter",
+  "fieldSettings",
+  "valueFieldSettings",
+  "toolbar",
+  "reportFilters",
+  "staleReport",
+  "fieldList",
+  "detailsTabs",
+  "detailsDialog"
+];
+function pivotChromeMounts(given, portals, made) {
+  const chrome = given;
+  if (chrome === void 0) return void 0;
+  if (typeof chrome !== "object" || chrome === null) {
+    throw new TypeError("An ExPivot's chrome is an object of Chrome slots, each a render function of its context (ADR-0390).");
+  }
+  const mounts = {};
+  for (const entry of Object.entries(chrome)) {
+    const name = entry[0];
+    const render = entry[1];
+    if (render === void 0) continue;
+    if (name === "grid") {
+      let grid = made.gridChrome;
+      if (grid === void 0 || grid.given !== render) {
+        grid = { given: render, mounts: chromeMounts(render, portals, made.grid) };
+        made.gridChrome = grid;
+      }
+      mounts[name] = grid.mounts;
+      continue;
+    }
+    if (!pivotSlots.includes(name)) {
+      mounts[name] = render;
+      continue;
+    }
+    if (typeof render !== "function") throw new TypeError(`An ExPivot's chrome.${name} is a render function of the slot's context (ADR-0390).`);
+    const before = made.pivot.get(name);
+    if (before !== void 0 && before.render === render) {
+      mounts[name] = before.mount;
+      continue;
+    }
+    const mount = (slot, context) => portals.mount(slot, () => {
+      const node = Reflect.apply(render, void 0, [context]);
+      return node;
+    });
+    made.pivot.set(name, { render, mount });
+    mounts[name] = mount;
+  }
+  return mounts;
+}
+var answered = /* @__PURE__ */ new WeakSet();
+function useViewedPart(context, what) {
+  const view = useSyncExternalStore(context.subscribe, context.view);
+  const control = useRef(null);
+  useLayoutEffect(() => {
+    if (context.focusRequest === 0 || answered.has(context)) return;
+    answered.add(context);
+    const target = control.current;
+    if (target === null) throw new Error(`The ${what} is not drawn: hand the hook's \`focus\` ref to it.`);
+    context.takeFocus(target);
+  }, [context, what]);
+  const [focus] = useState(() => (element) => {
+    control.current = element;
+  });
+  return { view, focus };
+}
+function usePivotPanel(context) {
+  const { view, focus } = useViewedPart(context, "panel's first control");
+  return { view, first: focus };
+}
+function usePivotPart(context) {
+  return useSyncExternalStore(context.subscribe, context.view);
+}
+function usePivotMenu(context) {
+  const { view, focus } = useViewedPart(context, "menu's first enabled command");
+  const first = view.commands.findIndex((command) => command.enabled);
+  return {
+    view,
+    item: (index) => {
+      const command = view.commands[index];
+      if (command === void 0) throw new RangeError(`The menu has ${view.commands.length} commands, not one at ${index}.`);
+      return {
+        role: command.checked === void 0 ? "menuitem" : "menuitemradio",
+        ...command.checked === void 0 ? {} : { "aria-checked": command.checked },
+        disabled: !command.enabled,
+        "data-ex-claims": "click",
+        onClick: command.invoke,
+        ...index === first ? { ref: focus } : {}
+      };
+    }
+  };
+}
+
+// src/ex-pivot.ts
+function withLocale(props, browserLocale) {
+  if (props.locale !== void 0) return props;
+  if (browserLocale === void 0) throw new Error("Internal: the browser's locale was not read for a pivot given none.");
+  return { ...props, locale: browserLocale };
+}
+function sameOptions(a, b) {
+  const keys = Object.keys(a);
+  return keys.length === Object.keys(b).length && keys.every((key) => Object.is(Reflect.get(a, key), Reflect.get(b, key)));
+}
+function ExPivot(props) {
+  const { chrome, ...given } = props;
+  const element = useRef2(null);
+  const pivot = useRef2(void 0);
+  const browserLocale = useRef2(void 0);
+  const handed = useRef2(void 0);
+  const portals = useGridPortals();
+  const [made] = useState2(() => ({ pivot: /* @__PURE__ */ new Map(), grid: /* @__PURE__ */ new Map() }));
+  const mounts = useMemo(() => pivotChromeMounts(chrome, portals, made), [chrome, portals, made]);
+  useLayoutEffect2(() => {
+    const root = element.current;
+    if (root === null) throw new Error("Internal: React mounted no element for the pivot to draw into.");
+    if (given.locale === void 0) browserLocale.current ??= browserPivotLocale(navigator.languages.length > 0 ? navigator.languages : [navigator.language]);
+    const options = withLocale(mounts === void 0 ? given : { ...given, chrome: mounts }, browserLocale.current);
+    if (pivot.current === void 0) {
+      portals.begin();
+      pivot.current = createPivot(root, options);
+    } else if (handed.current === void 0 || !sameOptions(handed.current, options)) {
+      pivot.current.update(options);
+    }
+    handed.current = options;
+  });
+  useLayoutEffect2(() => () => {
+    portals.end();
+    pivot.current?.destroy();
+    pivot.current = void 0;
+    handed.current = void 0;
+    browserLocale.current = void 0;
+  }, [portals]);
+  return createElement(Fragment, null, createElement("div", { ref: element }), ...portals.elements());
+}
+export {
+  ExPivot,
+  layPivotChrome,
+  pivotChromeMounts,
+  usePivotMenu,
+  usePivotPanel,
+  usePivotPart
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/ex-pivot.ts", "../src/chrome.ts"],
+  "sourcesContent": ["// The React Framework Adapter of ExPivot's Script Core (ADR-0370 section 1): it renders the element the pivot\n// draws into, hands the pivot its props, and unmounts it. It holds no state of the pivot's, draws nothing\n// inside its root but the Chrome slots it is handed, and decides nothing.\n\nimport { createElement, Fragment, useLayoutEffect, useMemo, useRef, useState, type ReactElement } from 'react';\nimport { browserPivotLocale, createPivot, type PivotHandle, type PivotViewOptions } from '@ex-grid/pivot';\nimport { useGridPortals } from '@ex-grid/react';\nimport { pivotChromeMounts, type ExPivotChrome, type PivotMountsMade } from './chrome';\n\n/**\n * An ExPivot's props: the Script Core's options, whole, its `chrome` as render functions. `locale` is the browser's\n * language where not given, the first of its languages the pivot writes in, read once, the first time the pivot is\n * given none (ADR-0370 section 10); the core never reads it on its own.\n */\nexport type ExPivotProps = Omit<PivotViewOptions, 'chrome'> & {\n    /** The parts a Wrapper's Chrome, or the Consumer's own, draws in place of the built-in markup (ADR-0390). */\n    readonly chrome?: ExPivotChrome;\n};\n\n/** The props as the core takes them: the browser's language where the Consumer gave no locale. */\nfunction withLocale(props: PivotViewOptions, browserLocale: string | undefined): PivotViewOptions {\n    if (props.locale !== undefined) return props;\n    if (browserLocale === undefined) throw new Error('Internal: the browser\\'s locale was not read for a pivot given none.');\n    return { ...props, locale: browserLocale };\n}\n\n// Whether `b` hands the pivot what `a` did, option by option: a render of the ExPivot's own, for a portal of its\n// Chrome slots, asks the pivot nothing.\nfunction sameOptions(a: PivotViewOptions, b: PivotViewOptions): boolean {\n    const keys = Object.keys(a);\n    return keys.length === Object.keys(b).length && keys.every(key => Object.is(Reflect.get(a, key), Reflect.get(b, key)));\n}\n\n/**\n * Excel's PivotTable, drawn by ExGrid, beside its Field List. The element it renders is the pivot's root,\n * which the Script Core owns; every render hands the core the props again, and what did not change asks\n * nothing again.\n */\nexport function ExPivot(props: ExPivotProps): ReactElement {\n    const { chrome, ...given } = props;\n    const element = useRef<HTMLDivElement>(null);\n    const pivot = useRef<PivotHandle | undefined>(undefined);\n    const browserLocale = useRef<string | undefined>(undefined);\n    // The options the pivot was handed last.\n    const handed = useRef<PivotViewOptions | undefined>(undefined);\n    // The Chrome slots' content, rendered by this component into the slots the pivot and its grids keep (ADR-0390).\n    const portals = useGridPortals();\n    // A render function handed again keeps its mount function, so the pivot does not draw its part again.\n    const [made] = useState<PivotMountsMade>(() => ({ pivot: new Map(), grid: new Map() }));\n    const mounts = useMemo(() => pivotChromeMounts(chrome, portals, made), [chrome, portals, made]);\n    // Drawn before the browser paints, so a mounted pivot is never seen empty.\n    useLayoutEffect(() => {\n        const root = element.current;\n        if (root === null) throw new Error('Internal: React mounted no element for the pivot to draw into.');\n        // The browser is asked only where the Consumer gave no locale: one that did needs nothing of it.\n        if (given.locale === undefined) browserLocale.current ??= browserPivotLocale(navigator.languages.length > 0 ? navigator.languages : [navigator.language]);\n        const options = withLocale(mounts === undefined ? given : { ...given, chrome: mounts }, browserLocale.current);\n        if (pivot.current === undefined) {\n            portals.begin();\n            pivot.current = createPivot(root, options);\n        } else if (handed.current === undefined || !sameOptions(handed.current, options)) {\n            pivot.current.update(options);\n        }\n        handed.current = options;\n    });\n    useLayoutEffect(() => () => {\n        // The portals go first: the contents the pivot takes away as it goes ask for no render of a component gone.\n        portals.end();\n        pivot.current?.destroy();\n        pivot.current = undefined;\n        handed.current = undefined;\n        browserLocale.current = undefined;\n    }, [portals]);\n    return createElement(Fragment, null, createElement('div', { ref: element }), ...portals.elements());\n}\n", "// ExPivot's Chrome slots for React (ADR-0061, ADR-0390 section 3): a Wrapper, or a Consumer's own design system,\n// renders a part of the pivot in place of the built-in markup, as a render function of what the pivot hands the\n// slot. The ExPivot draws it through a portal into the slot the pivot made. What the part means stays the pivot's: the\n// hooks here read the pivot's view of the part and give the keyboard to the control the pivot asks for, so a Wrapper\n// draws its own components and decides nothing.\n\nimport { useLayoutEffect, useRef, useState, useSyncExternalStore, type ReactNode } from 'react';\nimport type {\n    PivotDetailsDialogSlotContext, PivotDetailsTabsSlotContext,\n    PivotChrome, PivotFieldListSlotContext, PivotFieldSettingsSlotContext, PivotItemFilterSlotContext, PivotMenuSlotContext, PivotMenuView, PivotPanelSlotContext, PivotReportFiltersSlotContext,\n    PivotStaleReportSlotContext, PivotStandingSlotContext, PivotToolbarSlotContext, PivotValueFieldSettingsSlotContext,\n} from '@ex-grid/pivot';\nimport { chromeMounts, type ChromeMountsMade, type ExGridChrome, type GridPortals } from '@ex-grid/react';\n\n/**\n * The Chrome slots an ExPivot takes, each a render function of what the pivot hands that slot (ADR-0390 section 3),\n * and `grid`, ExGrid's own, which dresses the report's grid and Show Details' grids. A slot not given is drawn by the\n * built-in markup. A render function is read when its part opens; its answer is rendered as a component of its own,\n * so it may hold state, kept while the part stands, and a hook belongs in a component it renders.\n */\nexport interface ExPivotChrome {\n    /** ExGrid's Chrome for the report's grid and Show Details' grids; the Context Menu's commands are worded by the\n     * pivot. */\n    readonly grid?: ExGridChrome<unknown>;\n    /** A placed field's menu and the Layout menu, drawn with {@link usePivotMenu}. */\n    readonly menu?: (context: PivotMenuSlotContext) => ReactNode;\n    /** Filter\u2026, drawn with {@link usePivotPanel}. */\n    readonly itemFilter?: (context: PivotItemFilterSlotContext) => ReactNode;\n    /** Field Settings\u2026, drawn with {@link usePivotPanel}. */\n    readonly fieldSettings?: (context: PivotFieldSettingsSlotContext) => ReactNode;\n    /** Value Field Settings\u2026, drawn with {@link usePivotPanel}. */\n    readonly valueFieldSettings?: (context: PivotValueFieldSettingsSlotContext) => ReactNode;\n    /** The Pivot Toolbar, drawn with {@link usePivotPart}. */\n    readonly toolbar?: (context: PivotToolbarSlotContext) => ReactNode;\n    /** The report filter band, drawn with {@link usePivotPart}. */\n    readonly reportFilters?: (context: PivotReportFiltersSlotContext) => ReactNode;\n    /** The Stale Report's notice, drawn with {@link usePivotPart}. */\n    readonly staleReport?: (context: PivotStaleReportSlotContext) => ReactNode;\n    /** The Field List, drawn with {@link usePivotPart}. */\n    readonly fieldList?: (context: PivotFieldListSlotContext) => ReactNode;\n    /** The sheet tabs at the report's foot, while Show Details' records stand in a tab, drawn with {@link usePivotPart}. */\n    readonly detailsTabs?: (context: PivotDetailsTabsSlotContext) => ReactNode;\n    /** What the Show Details dialog draws inside the pivot's frame, drawn with {@link usePivotPart}. */\n    readonly detailsDialog?: (context: PivotDetailsDialogSlotContext) => ReactNode;\n}\n\n/** The slots of `over` given a render function laid over `under`: a slot given as `undefined` leaves the Wrapper's,\n * as one not named does. */\nfunction laid<T extends object>(under: T, over: Partial<T>): T {\n    return { ...under, ...Object.fromEntries(Object.entries(over).filter(([, slot]) => slot !== undefined)) };\n}\n\n/**\n * A design-system Wrapper's Chrome with the Consumer's `chrome` over it (ADR-0390): `pivot`, the Wrapper's pivot\n * slots, and `grid`, its ExGrid Chrome for the report's grid, each slot the Consumer names in its place. A slot given\n * as `undefined` leaves the Wrapper's, as one not named does. The grid's Chrome is the Wrapper's own object while the\n * Consumer names none of its slots, so a Chrome handed again with only pivot slots does not dress the report's grid\n * again. Every Wrapper of ExPivot lays its Chrome so, once per `given`.\n */\nexport function layPivotChrome(pivot: Omit<ExPivotChrome, 'grid'>, grid: ExGridChrome<unknown>, given: ExPivotChrome | undefined): ExPivotChrome {\n    if (given === undefined) return { ...pivot, grid };\n    const { grid: givenGrid, ...givenPivot } = given;\n    return { ...laid(pivot, givenPivot), grid: givenGrid === undefined ? grid : laid(grid, givenGrid) };\n}\n\n/** The mount functions made for an ExPivot's render functions: the pivot's slots', and the grid's. */\nexport interface PivotMountsMade {\n    /** The pivot's slots' render functions, and the mount function made for each, by slot. */\n    readonly pivot: Map<string, { readonly render: unknown; readonly mount: (slot: HTMLElement, context: unknown) => () => void }>;\n    /** The report grid's slots', as ExGrid for React makes them. */\n    readonly grid: ChromeMountsMade;\n    /** The report grid's Chrome last handed, and its mount functions. */\n    gridChrome?: { readonly given: unknown; readonly mounts: PivotChrome['grid'] };\n}\n\nconst pivotSlots: readonly string[] = ['menu', 'itemFilter', 'fieldSettings', 'valueFieldSettings', 'toolbar', 'reportFilters', 'staleReport', 'fieldList', 'detailsTabs',\n    'detailsDialog'];\n\n/** The ExPivot's Chrome as the pivot takes it: each slot's render function as a mount function rendering it through\n * the ExPivot's portals, and `grid`'s as ExGrid for React makes its own. A render function handed again keeps its\n * mount function. Which slots there are is the pivot's to check; a render function that is not a function is named\n * here, in React's terms. Exported for the family's Framework Adapters, whose products hand ExPivot's Chrome on to the\n * pivots they draw, not for a Consumer. */\nexport function pivotChromeMounts(given: ExPivotChrome | undefined, portals: GridPortals, made: PivotMountsMade): PivotChrome | undefined {\n    // Checked as a script may hand it, whatever its type says.\n    const chrome: unknown = given;\n    if (chrome === undefined) return undefined;\n    if (typeof chrome !== 'object' || chrome === null) {\n        throw new TypeError('An ExPivot\\'s chrome is an object of Chrome slots, each a render function of its context (ADR-0390).');\n    }\n    const mounts: Record<string, unknown> = {};\n    for (const entry of Object.entries(chrome)) {\n        const name = entry[0];\n        const render: unknown = entry[1];\n        if (render === undefined) continue;\n        if (name === 'grid') {\n            // The grid's mounts are made again only for another grid chrome, so its standing parts keep theirs.\n            let grid = made.gridChrome;\n            if (grid === undefined || grid.given !== render) {\n                // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- checked by chromeMounts, as ExGrid for React checks its own chrome\n                grid = { given: render, mounts: chromeMounts(render as ExGridChrome<unknown>, portals, made.grid) };\n                made.gridChrome = grid;\n            }\n            mounts[name] = grid.mounts;\n            continue;\n        }\n        // A slot the pivot does not have is handed on, for the pivot to refuse by name.\n        if (!pivotSlots.includes(name)) {\n            mounts[name] = render;\n            continue;\n        }\n        if (typeof render !== 'function') throw new TypeError(`An ExPivot's chrome.${name} is a render function of the slot's context (ADR-0390).`);\n        const before = made.pivot.get(name);\n        if (before !== undefined && before.render === render) {\n            mounts[name] = before.mount;\n            continue;\n        }\n        const mount = (slot: HTMLElement, context: unknown): (() => void) => portals.mount(slot, () => {\n            // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- the pivot hands each slot's mount that slot's context, the one its render function takes\n            const node = Reflect.apply(render, undefined, [context]) as ReactNode;\n            return node;\n        });\n        made.pivot.set(name, { render, mount });\n        mounts[name] = mount;\n    }\n    return mounts;\n}\n\n/** What a part's context offers every hook here: its view, and the keyboard's requests. */\ninterface ViewedPart<View> {\n    readonly view: () => View;\n    readonly subscribe: (listener: () => void) => () => void;\n    readonly focusRequest: number;\n    readonly takeFocus: (control: HTMLElement) => void;\n}\n\n/** The contexts whose request for the keyboard has been answered. Each request comes in a context of its own, so one\n * answered is never answered again: not by a component of the contents mounted after it, nor by an effect run twice. */\nconst answered = new WeakSet<object>();\n\n/** The view, read again at each change, and the ref of the control a request for the keyboard is for, focused once it\n * is drawn. */\nfunction useViewedPart<View>(context: ViewedPart<View>, what: string): { readonly view: View; readonly focus: (control: HTMLElement | null) => void } {\n    const view = useSyncExternalStore(context.subscribe, context.view);\n    const control = useRef<HTMLElement | null>(null);\n    useLayoutEffect(() => {\n        if (context.focusRequest === 0 || answered.has(context)) return;\n        answered.add(context);\n        const target = control.current;\n        if (target === null) throw new Error(`The ${what} is not drawn: hand the hook's \\`focus\\` ref to it.`);\n        context.takeFocus(target);\n    }, [context, what]);\n    // Made once, so a render hands React the same ref and it does not take it away and back.\n    const [focus] = useState(() => (element: HTMLElement | null): void => { control.current = element; });\n    return { view, focus };\n}\n\n/** What {@link usePivotPanel} hands a panel's contents. */\nexport interface PivotPanelHandles<View> {\n    /** What the panel shows now, drawn again at each change the pivot makes to it. */\n    readonly view: View;\n    /** Takes the panel's first control: the one each request of the pivot's for the keyboard is for. */\n    readonly first: (control: HTMLElement | null) => void;\n}\n\n/**\n * Draws one of the pivot's panels from its context (ADR-0390 section 3): Filter\u2026, Field Settings\u2026 or Value Field\n * Settings\u2026. The view is the pivot's draft, read again at each change; each choice goes to the context's setter, and\n * the hook gives the panel's first control the keyboard at each request, once it is drawn, through the pivot.\n */\nexport function usePivotPanel<View>(context: PivotPanelSlotContext & { readonly view: () => View }): PivotPanelHandles<View> {\n    const { view, focus } = useViewedPart(context, 'panel\\'s first control');\n    return { view, first: focus };\n}\n\n/**\n * Draws one of the pivot's standing parts from its context (ADR-0390 section 3): the Pivot Toolbar, the report filter\n * band, the Stale Report's notice or the Field List. The view is the pivot's, read again at each change; each press goes to the\n * context's callback, and each control and anchor is handed in by its `ref`, `context.control(name)` and\n * `context.anchor(name)`, so the pivot gives the keyboard to the control it means and places a popup's frame in its\n * anchor itself.\n */\nexport function usePivotPart<View>(context: PivotStandingSlotContext<View>): View {\n    return useSyncExternalStore(context.subscribe, context.view);\n}\n\n/** The props {@link usePivotMenu} hands each command's control: spread them onto it. */\nexport interface PivotMenuItemProps {\n    /** A choice is a `menuitemradio`, any other command a `menuitem`. */\n    readonly role: 'menuitem' | 'menuitemradio';\n    /** On a choice: whether it is the current one. */\n    readonly 'aria-checked'?: boolean;\n    /** Whether the command cannot run now; a disabled command is shown, never left out. */\n    readonly disabled: boolean;\n    /** Claims the click for the pivot's Input Order (ADR-0240). */\n    readonly 'data-ex-claims': 'click';\n    /** Runs the command the pivot drew last under this one's id. */\n    readonly onClick: () => void;\n    /** On the first enabled command: the one a request for the keyboard is for. */\n    readonly ref?: (control: HTMLElement | null) => void;\n}\n\n/** What {@link usePivotMenu} hands a menu's contents. */\nexport interface PivotMenuHandles {\n    /** What the menu shows now: its commands, in the pivot's order, with their group headings. */\n    readonly view: PivotMenuView;\n    /** The props of the command at `index` in the view's commands. */\n    readonly item: (index: number) => PivotMenuItemProps;\n}\n\n/**\n * Draws a menu from its context (ADR-0390 section 3): one control per command, in the pivot's order, a choice as a\n * `menuitemradio` marked while it is the current one. A press runs the command the pivot drew last under its id, and\n * the first enabled command takes the keyboard at each request of the pivot's.\n */\nexport function usePivotMenu(context: PivotMenuSlotContext): PivotMenuHandles {\n    const { view, focus } = useViewedPart(context, 'menu\\'s first enabled command');\n    const first = view.commands.findIndex(command => command.enabled);\n    return {\n        view,\n        item: index => {\n            const command = view.commands[index];\n            if (command === undefined) throw new RangeError(`The menu has ${view.commands.length} commands, not one at ${index}.`);\n            return {\n                role: command.checked === undefined ? 'menuitem' : 'menuitemradio',\n                ...(command.checked === undefined ? {} : { 'aria-checked': command.checked }),\n                disabled: !command.enabled,\n                'data-ex-claims': 'click',\n                onClick: command.invoke,\n                ...(index === first ? { ref: focus } : {}),\n            };\n        },\n    };\n}\n"],
+  "mappings": ";AAIA,SAAS,eAAe,UAAU,mBAAAA,kBAAiB,SAAS,UAAAC,SAAQ,YAAAC,iBAAmC;AACvG,SAAS,oBAAoB,mBAA4D;AACzF,SAAS,sBAAsB;;;ACA/B,SAAS,iBAAiB,QAAQ,UAAU,4BAA4C;AAMxF,SAAS,oBAAgF;AAoCzF,SAAS,KAAuB,OAAU,MAAqB;AAC3D,SAAO,EAAE,GAAG,OAAO,GAAG,OAAO,YAAY,OAAO,QAAQ,IAAI,EAAE,OAAO,CAAC,CAAC,EAAE,IAAI,MAAM,SAAS,MAAS,CAAC,EAAE;AAC5G;AASO,SAAS,eAAe,OAAoC,MAA6B,OAAiD;AAC7I,MAAI,UAAU,OAAW,QAAO,EAAE,GAAG,OAAO,KAAK;AACjD,QAAM,EAAE,MAAM,WAAW,GAAG,WAAW,IAAI;AAC3C,SAAO,EAAE,GAAG,KAAK,OAAO,UAAU,GAAG,MAAM,cAAc,SAAY,OAAO,KAAK,MAAM,SAAS,EAAE;AACtG;AAYA,IAAM,aAAgC;AAAA,EAAC;AAAA,EAAQ;AAAA,EAAc;AAAA,EAAiB;AAAA,EAAsB;AAAA,EAAW;AAAA,EAAiB;AAAA,EAAe;AAAA,EAAa;AAAA,EACxJ;AAAe;AAOZ,SAAS,kBAAkB,OAAkC,SAAsB,MAAgD;AAEtI,QAAM,SAAkB;AACxB,MAAI,WAAW,OAAW,QAAO;AACjC,MAAI,OAAO,WAAW,YAAY,WAAW,MAAM;AAC/C,UAAM,IAAI,UAAU,qGAAsG;AAAA,EAC9H;AACA,QAAM,SAAkC,CAAC;AACzC,aAAW,SAAS,OAAO,QAAQ,MAAM,GAAG;AACxC,UAAM,OAAO,MAAM,CAAC;AACpB,UAAM,SAAkB,MAAM,CAAC;AAC/B,QAAI,WAAW,OAAW;AAC1B,QAAI,SAAS,QAAQ;AAEjB,UAAI,OAAO,KAAK;AAChB,UAAI,SAAS,UAAa,KAAK,UAAU,QAAQ;AAE7C,eAAO,EAAE,OAAO,QAAQ,QAAQ,aAAa,QAAiC,SAAS,KAAK,IAAI,EAAE;AAClG,aAAK,aAAa;AAAA,MACtB;AACA,aAAO,IAAI,IAAI,KAAK;AACpB;AAAA,IACJ;AAEA,QAAI,CAAC,WAAW,SAAS,IAAI,GAAG;AAC5B,aAAO,IAAI,IAAI;AACf;AAAA,IACJ;AACA,QAAI,OAAO,WAAW,WAAY,OAAM,IAAI,UAAU,uBAAuB,IAAI,yDAAyD;AAC1I,UAAM,SAAS,KAAK,MAAM,IAAI,IAAI;AAClC,QAAI,WAAW,UAAa,OAAO,WAAW,QAAQ;AAClD,aAAO,IAAI,IAAI,OAAO;AACtB;AAAA,IACJ;AACA,UAAM,QAAQ,CAAC,MAAmB,YAAmC,QAAQ,MAAM,MAAM,MAAM;AAE3F,YAAM,OAAO,QAAQ,MAAM,QAAQ,QAAW,CAAC,OAAO,CAAC;AACvD,aAAO;AAAA,IACX,CAAC;AACD,SAAK,MAAM,IAAI,MAAM,EAAE,QAAQ,MAAM,CAAC;AACtC,WAAO,IAAI,IAAI;AAAA,EACnB;AACA,SAAO;AACX;AAYA,IAAM,WAAW,oBAAI,QAAgB;AAIrC,SAAS,cAAoB,SAA2B,MAA8F;AAClJ,QAAM,OAAO,qBAAqB,QAAQ,WAAW,QAAQ,IAAI;AACjE,QAAM,UAAU,OAA2B,IAAI;AAC/C,kBAAgB,MAAM;AAClB,QAAI,QAAQ,iBAAiB,KAAK,SAAS,IAAI,OAAO,EAAG;AACzD,aAAS,IAAI,OAAO;AACpB,UAAM,SAAS,QAAQ;AACvB,QAAI,WAAW,KAAM,OAAM,IAAI,MAAM,OAAO,IAAI,qDAAqD;AACrG,YAAQ,UAAU,MAAM;AAAA,EAC5B,GAAG,CAAC,SAAS,IAAI,CAAC;AAElB,QAAM,CAAC,KAAK,IAAI,SAAS,MAAM,CAAC,YAAsC;AAAE,YAAQ,UAAU;AAAA,EAAS,CAAC;AACpG,SAAO,EAAE,MAAM,MAAM;AACzB;AAeO,SAAS,cAAoB,SAAyF;AACzH,QAAM,EAAE,MAAM,MAAM,IAAI,cAAc,SAAS,uBAAwB;AACvE,SAAO,EAAE,MAAM,OAAO,MAAM;AAChC;AASO,SAAS,aAAmB,SAA+C;AAC9E,SAAO,qBAAqB,QAAQ,WAAW,QAAQ,IAAI;AAC/D;AA+BO,SAAS,aAAa,SAAiD;AAC1E,QAAM,EAAE,MAAM,MAAM,IAAI,cAAc,SAAS,8BAA+B;AAC9E,QAAM,QAAQ,KAAK,SAAS,UAAU,aAAW,QAAQ,OAAO;AAChE,SAAO;AAAA,IACH;AAAA,IACA,MAAM,WAAS;AACX,YAAM,UAAU,KAAK,SAAS,KAAK;AACnC,UAAI,YAAY,OAAW,OAAM,IAAI,WAAW,gBAAgB,KAAK,SAAS,MAAM,yBAAyB,KAAK,GAAG;AACrH,aAAO;AAAA,QACH,MAAM,QAAQ,YAAY,SAAY,aAAa;AAAA,QACnD,GAAI,QAAQ,YAAY,SAAY,CAAC,IAAI,EAAE,gBAAgB,QAAQ,QAAQ;AAAA,QAC3E,UAAU,CAAC,QAAQ;AAAA,QACnB,kBAAkB;AAAA,QAClB,SAAS,QAAQ;AAAA,QACjB,GAAI,UAAU,QAAQ,EAAE,KAAK,MAAM,IAAI,CAAC;AAAA,MAC5C;AAAA,IACJ;AAAA,EACJ;AACJ;;;ADrNA,SAAS,WAAW,OAAyB,eAAqD;AAC9F,MAAI,MAAM,WAAW,OAAW,QAAO;AACvC,MAAI,kBAAkB,OAAW,OAAM,IAAI,MAAM,qEAAsE;AACvH,SAAO,EAAE,GAAG,OAAO,QAAQ,cAAc;AAC7C;AAIA,SAAS,YAAY,GAAqB,GAA8B;AACpE,QAAM,OAAO,OAAO,KAAK,CAAC;AAC1B,SAAO,KAAK,WAAW,OAAO,KAAK,CAAC,EAAE,UAAU,KAAK,MAAM,SAAO,OAAO,GAAG,QAAQ,IAAI,GAAG,GAAG,GAAG,QAAQ,IAAI,GAAG,GAAG,CAAC,CAAC;AACzH;AAOO,SAAS,QAAQ,OAAmC;AACvD,QAAM,EAAE,QAAQ,GAAG,MAAM,IAAI;AAC7B,QAAM,UAAUC,QAAuB,IAAI;AAC3C,QAAM,QAAQA,QAAgC,MAAS;AACvD,QAAM,gBAAgBA,QAA2B,MAAS;AAE1D,QAAM,SAASA,QAAqC,MAAS;AAE7D,QAAM,UAAU,eAAe;AAE/B,QAAM,CAAC,IAAI,IAAIC,UAA0B,OAAO,EAAE,OAAO,oBAAI,IAAI,GAAG,MAAM,oBAAI,IAAI,EAAE,EAAE;AACtF,QAAM,SAAS,QAAQ,MAAM,kBAAkB,QAAQ,SAAS,IAAI,GAAG,CAAC,QAAQ,SAAS,IAAI,CAAC;AAE9F,EAAAC,iBAAgB,MAAM;AAClB,UAAM,OAAO,QAAQ;AACrB,QAAI,SAAS,KAAM,OAAM,IAAI,MAAM,gEAAgE;AAEnG,QAAI,MAAM,WAAW,OAAW,eAAc,YAAY,mBAAmB,UAAU,UAAU,SAAS,IAAI,UAAU,YAAY,CAAC,UAAU,QAAQ,CAAC;AACxJ,UAAM,UAAU,WAAW,WAAW,SAAY,QAAQ,EAAE,GAAG,OAAO,QAAQ,OAAO,GAAG,cAAc,OAAO;AAC7G,QAAI,MAAM,YAAY,QAAW;AAC7B,cAAQ,MAAM;AACd,YAAM,UAAU,YAAY,MAAM,OAAO;AAAA,IAC7C,WAAW,OAAO,YAAY,UAAa,CAAC,YAAY,OAAO,SAAS,OAAO,GAAG;AAC9E,YAAM,QAAQ,OAAO,OAAO;AAAA,IAChC;AACA,WAAO,UAAU;AAAA,EACrB,CAAC;AACD,EAAAA,iBAAgB,MAAM,MAAM;AAExB,YAAQ,IAAI;AACZ,UAAM,SAAS,QAAQ;AACvB,UAAM,UAAU;AAChB,WAAO,UAAU;AACjB,kBAAc,UAAU;AAAA,EAC5B,GAAG,CAAC,OAAO,CAAC;AACZ,SAAO,cAAc,UAAU,MAAM,cAAc,OAAO,EAAE,KAAK,QAAQ,CAAC,GAAG,GAAG,QAAQ,SAAS,CAAC;AACtG;",
+  "names": ["useLayoutEffect", "useRef", "useState", "useRef", "useState", "useLayoutEffect"]
+}

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@ex-grid/pivot-react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0-rc.1",
+  "description": "ExPivot for React: the Framework Adapter of ExPivot's Script Core, which mounts Excel's PivotTable, drawn by ExGrid, in a React tree.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AkiraMisawa/ex-grid.git",
+    "directory": "packages/pivot-react"
+  },
+  "homepage": "https://akiramisawa.github.io/ex-grid/",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/index.js",
+    "dist/index.js.map",
+    "dist/index.d.ts"
+  ],
+  "dependencies": {
+    "@ex-grid/pivot": "0.2.0-rc.1",
+    "@ex-grid/react": "0.2.0-rc.1"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  }
+}