@bmxc/pami-react 0.0.0-stage → 0.1.0-beta.2

package/src/components.ts

@@ -0,0 +1,94 @@
+'use client';
+
+/**
+ * Generated by scripts/split-react-components.mjs. Do not edit — regenerated on
+ * every core build. Each component lives in its own module under ./components/
+ * so bundlers only ever pull in what is imported.
+ */
+/* barrel generated by scripts/split-react-components.mjs */
+
+export * from './components/PamiAccordion.js';
+export * from './components/PamiAccordionItem.js';
+export * from './components/PamiAppBar.js';
+export * from './components/PamiAreaChart.js';
+export * from './components/PamiAutocomplete.js';
+export * from './components/PamiAvatar.js';
+export * from './components/PamiBadge.js';
+export * from './components/PamiBarChart.js';
+export * from './components/PamiBottomSheet.js';
+export * from './components/PamiBreadcrumbItem.js';
+export * from './components/PamiBreadcrumbs.js';
+export * from './components/PamiButton.js';
+export * from './components/PamiButtonGroup.js';
+export * from './components/PamiCallout.js';
+export * from './components/PamiCard.js';
+export * from './components/PamiCheckbox.js';
+export * from './components/PamiChip.js';
+export * from './components/PamiColorPicker.js';
+export * from './components/PamiDatePicker.js';
+export * from './components/PamiDialog.js';
+export * from './components/PamiDivider.js';
+export * from './components/PamiFab.js';
+export * from './components/PamiFabMenu.js';
+export * from './components/PamiFabMenuItem.js';
+export * from './components/PamiIcon.js';
+export * from './components/PamiIconButton.js';
+export * from './components/PamiLineChart.js';
+export * from './components/PamiList.js';
+export * from './components/PamiListItem.js';
+export * from './components/PamiLoadingIndicator.js';
+export * from './components/PamiMenu.js';
+export * from './components/PamiMenuItem.js';
+export * from './components/PamiMenuItemGroup.js';
+export * from './components/PamiMeter.js';
+export * from './components/PamiMultiSelect.js';
+export * from './components/PamiNavigationBar.js';
+export * from './components/PamiNavigationGroup.js';
+export * from './components/PamiNavigationRail.js';
+export * from './components/PamiNavigationRailTab.js';
+export * from './components/PamiNavigationTab.js';
+export * from './components/PamiNumberField.js';
+export * from './components/PamiOrganizationChart.js';
+export * from './components/PamiOtpField.js';
+export * from './components/PamiPieChart.js';
+export * from './components/PamiProgressIndicator.js';
+export * from './components/PamiRadio.js';
+export * from './components/PamiRating.js';
+export * from './components/PamiRipple.js';
+export * from './components/PamiSearch.js';
+export * from './components/PamiSegmentedButton.js';
+export * from './components/PamiSegmentedButtonSet.js';
+export * from './components/PamiSelect.js';
+export * from './components/PamiSelectOption.js';
+export * from './components/PamiSideSheet.js';
+export * from './components/PamiSkeleton.js';
+export * from './components/PamiSlider.js';
+export * from './components/PamiSnackbar.js';
+export * from './components/PamiSparkline.js';
+export * from './components/PamiSplitButton.js';
+export * from './components/PamiStatusDot.js';
+export * from './components/PamiStep.js';
+export * from './components/PamiStepper.js';
+export * from './components/PamiSubMenuItem.js';
+export * from './components/PamiSwitch.js';
+export * from './components/PamiTab.js';
+export * from './components/PamiTabPanel.js';
+export * from './components/PamiTabPanels.js';
+export * from './components/PamiTable.js';
+export * from './components/PamiTableBody.js';
+export * from './components/PamiTableCell.js';
+export * from './components/PamiTableContainer.js';
+export * from './components/PamiTableExpandToggle.js';
+export * from './components/PamiTableFoot.js';
+export * from './components/PamiTableHead.js';
+export * from './components/PamiTablePagination.js';
+export * from './components/PamiTableRow.js';
+export * from './components/PamiTableSortLabel.js';
+export * from './components/PamiTableToolbar.js';
+export * from './components/PamiTabs.js';
+export * from './components/PamiTag.js';
+export * from './components/PamiTextField.js';
+export * from './components/PamiTimePicker.js';
+export * from './components/PamiToolbar.js';
+export * from './components/PamiTooltip.js';
+export * from './components/PamiTransferList.js';

package/src/index.ts

@@ -0,0 +1,10 @@
+// Auto-generated React proxies for Pami components
+// This file will be populated by @stencil/react-output-target after build
+
+// Re-export everything from the generated components file
+// After building core, this file will be at ./components.ts
+// (.js extension: node16 ESM consumers resolve the emitted d.ts/js verbatim,
+// so the specifier must be extension-qualified.)
+export * from './components.js';
+export { useOverlay } from './use-overlay.js';
+export type { PamiOverlayElement, UseOverlayOptions } from './use-overlay.js';

package/src/server.ts

@@ -0,0 +1,5 @@
+// SSR entry — React wrappers that server-render each component's Declarative
+// Shadow DOM via @bmxc/pami-elements/hydrate, then hydrate on the client. Import these
+// (instead of the client components from '@bmxc/pami-react') when you want styled
+// server markup on first paint, e.g. in a Next.js App Router server component.
+export * from './components.server.js';

package/src/use-overlay.readme.md

@@ -0,0 +1,76 @@
+# `useOverlay`
+
+Keep a conditionally mounted Core dialog, side sheet or menu in React until
+its native closing animation finishes. The hook opens the element after mount
+and uses Core's `whenClosed()` completion contract to decide when React may
+remove it.
+
+```tsx
+import { useRef, useState } from 'react';
+import { PamiButton, PamiDialog, useOverlay } from '@bmxc/pami-react';
+
+function CreateDialog({ onClosed }: { onClosed: () => void }) {
+  const dialog = useRef<HTMLPamiDialogElement>(null);
+  const overlay = useOverlay(dialog, { onClosed });
+
+  return (
+    <PamiDialog ref={dialog} headline="Create project" {...overlay}>
+      {/* Form contents use the regular Core field components. */}
+      <PamiButton slot="actions" variant="text"
+        onPamiClick={() => { void dialog.current?.close(); }}>
+        Cancel
+      </PamiButton>
+    </PamiDialog>
+  );
+}
+
+export function Projects() {
+  const [creating, setCreating] = useState(false);
+  return <>
+    <PamiButton onPamiClick={() => setCreating(true)}>Create project</PamiButton>
+    {creating && <CreateDialog onClosed={() => setCreating(false)} />}
+  </>;
+}
+```
+
+`useOverlay(ref, options)` returns `{ onPamiClose }`. Spread it onto the same
+`PamiDialog`, `PamiSideSheet` or `PamiMenu` that receives the ref. These components
+must come from the matching Core release with `show()`, `close()` and
+`whenClosed()` methods.
+
+| Option | Timing |
+| --- | --- |
+| `onClosing` | At the overlay's own native `pamiClose` event; use for early busy-state or draft cleanup. |
+| `onClosed` | Once the native open cycle and shell exit finish; use to remove the React component. |
+
+- Close by calling `ref.current.close()`. Do not remove the component directly
+  in `onPamiClose`, or the exit animation cannot complete.
+- `close()` requests dismissal; its returned promise is **not** the exit
+  animation boundary. The hook waits for `whenClosed()` separately.
+- A close requested before the initial open finishes still calls `onClosed`
+  once. No `onClosing` callback fires when Core never entered its open state
+  and consequently emitted no `pamiClose` event.
+- Nested controls may bubble their own `pamiClose` events. The hook ignores them
+  using the event target and current target, so closing a select does not
+  dismiss the surrounding dialog.
+- Callback props may change without reopening the overlay; the latest
+  callbacks are used. React StrictMode's setup/cleanup replay does not report
+  a user dismissal, and an unmounted component cannot call a late `onClosed`.
+- Keep the ref stable with `useRef`. Mount a fresh component for each new
+  overlay session. The hook is intended for conditional overlays; persistent
+  anchor-managed FAB menus own their opening lifecycle. A time picker uses
+  `hide()` and is not supported by this hook.
+
+## Tests
+
+From the repository root, after installing the workspace dependencies:
+
+```sh
+pnpm --filter @bmxc/pami-react test:overlay
+```
+
+The suite runs the actual hook with React DOM and StrictMode in jsdom. A small
+custom element controls the native animation completion boundary, so lifecycle
+ordering is deterministic. Core's component tests cover actual overlay motion
+and rendering separately. The suite uses the existing Core workspace's
+`esbuild` and `jsdom` development dependencies and does not require a build.

package/src/use-overlay.ts

@@ -0,0 +1,60 @@
+'use client';
+
+import { useCallback, useEffect, useRef } from 'react';
+import type { RefObject } from 'react';
+
+export interface PamiOverlayElement extends HTMLElement {
+  show(): Promise<void>;
+  close(): Promise<void>;
+  whenClosed(): Promise<void>;
+}
+
+export interface UseOverlayOptions {
+  /** Called at the native close event, before the shell exit completes. */
+  onClosing?: () => void;
+  /** Called after Core's exit completes. Safe to remove the React component. */
+  onClosed?: () => void;
+}
+
+/**
+ * Open a conditionally mounted Core overlay and retain it through its exit.
+ * Spread the returned event handler onto PamiDialog, PamiSideSheet, or PamiMenu.
+ * Persistent anchor-managed FAB menus should manage their own open lifecycle.
+ */
+export function useOverlay<T extends PamiOverlayElement>(ref: RefObject<T | null>, options: UseOverlayOptions = {}) {
+  const callbacks = useRef(options);
+  callbacks.current = options;
+  const active = useRef<T | null>(null);
+  const closing = useRef(false);
+
+  useEffect(() => {
+    const element = ref.current;
+    if (!element) return;
+    let disposed = false;
+    active.current = element;
+    closing.current = false;
+    // A close before the first paint cancels show() without emitting pamiClose.
+    // Observe the native cycle independently so that case also releases the
+    // React host. Each effect instance owns one completion (StrictMode-safe).
+    void (async () => {
+      await element.show();
+      if (disposed) return;
+      await element.whenClosed();
+      if (!disposed && active.current === element) callbacks.current.onClosed?.();
+    })();
+    return () => {
+      disposed = true;
+      active.current = null;
+      void element.close();
+    };
+  }, [ref]);
+
+  const onPamiClose = useCallback((event: CustomEvent<void>) => {
+    const element = ref.current;
+    if (!element || active.current !== element || closing.current || event.target !== element || event.currentTarget !== element) return;
+    closing.current = true;
+    callbacks.current.onClosing?.();
+  }, [ref]);
+
+  return { onPamiClose };
+}