phonux 0.1.0

package/PanelRowSlot.d.ts

@@ -0,0 +1,74 @@
+import * as React from 'react';
+import { type TargetAndTransition } from 'motion/react';
+/**
+ * The one spacing value used everywhere a gap is needed in this row.
+ * @public
+ */
+export declare const GAP = 16;
+/** The timing/easing every panel slide uses. The SAME object as SLOT_TRANSITION, not a copy: a host animates
+ * its own row "the same as a panel" by this reference (test/row-shell-style.test.ts pins it).
+ * @public */
+export declare const PANEL_TRANSITION: {
+    duration: number;
+    ease: [number, number, number, number];
+};
+/**
+ * One live panel's animated slot, absolutely positioned at its own `leftOffset` so adding,
+ * removing or resizing a panel never disturbs the ones to its left; `x`, not `left`, so the
+ * browser composites it. Motion drives enter/exit (AnimatePresence keeps an outgoing node
+ * mounted through its own unmount commit, unlike a plain CSS transition), and its Web Animations
+ * API is immune to a theme's transition/animation:none reset, which must stay scoped there and never reach
+ * transform/opacity, or it would kill this silently.
+ */
+export interface PanelRowSlotMotion {
+    readonly initial: TargetAndTransition;
+    readonly animate: TargetAndTransition;
+    readonly exit: TargetAndTransition;
+    readonly transition: typeof PANEL_TRANSITION;
+}
+type ExitDirection = 'down' | 'left' | 'right';
+/**
+ * The pure values behind one PanelRowSlot render, split out so a test can assert exact motion
+ * values without mounting a component. `exit` stays entirely local to this function: 'down' needs a second
+ * axis and its own transition, 'left' a target independent of `leftOffset`; neither fits directionalTransition's
+ * symmetric default.
+ */
+export declare function panelRowSlotMotion(leftOffset: number, width: number, phoneHeight: number, enterDirection: 'left' | 'right', exitDirection: ExitDirection): PanelRowSlotMotion;
+/**
+ * One entry's animated slot in the row: its position, width, enter/exit motion and stacking.
+ * @public
+ */
+export declare function PanelRowSlot({ leftOffset, width, phoneHeight, enterDirection, exitDirection, zIndex, children, }: {
+    /** This slot's own rest x position -- the caller's running sum of every PRECEDING present item's own width plus one gap. */
+    leftOffset: number;
+    /** This panel's own width (`panelWidthOf`), also this slot's enter/exit travel distance (`panelRowSlotMotion`'s `ownSpan`). */
+    width: number;
+    phoneHeight: number;
+    /** Computed by the caller (panelRowOrder.ts's `resolveEnterDirection`, or an explicit gesture side).
+     * Must be correct on this component's FIRST render after the item (re)appears -- AnimatePresence
+     * has no later render of a fresh mount to fix a wrong guess. */
+    enterDirection: 'left' | 'right';
+    /** Must be correct on this component's LAST render before it leaves the `live`-filtered array --
+     * AnimatePresence has no later render of a removed child to fix a wrong guess. */
+    exitDirection: 'down' | 'left' | 'right';
+    /**
+     * Each slot's `motion.div` carries a `transform`, so it is its OWN stacking context and a child's `zIndex`
+     * cannot compare against a SIBLING slot: stacking between slots (e.g. a raised column above a panel sliding
+     * left behind it) must be set HERE, on the slot, not on what renders inside it. Defaults to 0.
+     */
+    zIndex?: number;
+    children: React.ReactNode;
+}): React.JSX.Element;
+/**
+ * The element a resize animates: an INNER box, never the slot, which owns `exit` (Motion's docs warn against
+ * `layout` and `exit` on one element). A layout animation sets the real size once and animates a transform
+ * toward it, so the view never re-lays out mid-resize; `layout="size"` because the slot's `x` already animates
+ * position. A view renders it inside its own slot, so a view that never resizes needs no wrapper.
+ * @public
+ */
+export declare function PanelSizeBox({ width, height, children }: {
+    width: number;
+    height: number;
+    children: React.ReactNode;
+}): React.JSX.Element;
+export {};

package/PanelRowSlot.js

@@ -0,0 +1,68 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { motion } from 'motion/react';
+import { DRAG_CLOSE } from './dragToClose.js';
+import { SLOT_TRANSITION, directionalTransition } from './directionalTransition.js';
+/**
+ * The one spacing value used everywhere a gap is needed in this row.
+ * @public
+ */
+export const GAP = 16;
+/** The timing/easing every panel slide uses. The SAME object as SLOT_TRANSITION, not a copy: a host animates
+ * its own row "the same as a panel" by this reference (test/row-shell-style.test.ts pins it).
+ * @public */
+export const PANEL_TRANSITION = SLOT_TRANSITION;
+/**
+ * The pure values behind one PanelRowSlot render, split out so a test can assert exact motion
+ * values without mounting a component. `exit` stays entirely local to this function: 'down' needs a second
+ * axis and its own transition, 'left' a target independent of `leftOffset`; neither fits directionalTransition's
+ * symmetric default.
+ */
+export function panelRowSlotMotion(leftOffset, width, phoneHeight, enterDirection, exitDirection) {
+    // This panel's OWN footprint (its width plus one gap) is how far it must travel to clear the row edge,
+    // so the distance is per panel: a wider one travels further.
+    const ownSpan = width + GAP;
+    const rest = leftOffset;
+    // Positive distance enters from the right (directionalTransition.ts's own sign convention); a negative
+    // one enters from the left -- see panelRowOrder.ts for who decides which.
+    const enterDistance = enterDirection === 'left' ? -ownSpan : ownSpan;
+    const { initial, animate, transition } = directionalTransition('x', rest, enterDistance);
+    // 'down': a close, timed to DragToClose's exit so trash and drag closes read as one motion (DragToClose calls
+    // `onClose` after its own `y` animation, so this ramps in under a box already off-screen). 'left'/'right': a
+    // park, off the edge it was hidden past, so a close never looks like a park.
+    const exit = exitDirection === 'down'
+        ? { x: rest, y: phoneHeight, opacity: 0, transition: { duration: DRAG_CLOSE.exitSeconds, ease: 'easeIn' } }
+        : exitDirection === 'right'
+            ? { x: rest + ownSpan, opacity: 0 }
+            : { x: -ownSpan, opacity: 0 };
+    return { initial, animate, exit, transition };
+}
+/**
+ * One entry's animated slot in the row: its position, width, enter/exit motion and stacking.
+ * @public
+ */
+export function PanelRowSlot({ leftOffset, width, phoneHeight, enterDirection, exitDirection, zIndex, children, }) {
+    const { initial, animate, exit, transition } = panelRowSlotMotion(leftOffset, width, phoneHeight, enterDirection, exitDirection);
+    return (_jsx(motion.div
+    // Enters from one own-width-plus-gap span beyond its destination, right or left per `enterDirection` above.
+    , { 
+        // Enters from one own-width-plus-gap span beyond its destination, right or left per `enterDirection` above.
+        initial: initial, animate: animate, exit: exit, transition: transition, style: {
+            position: 'absolute',
+            top: 0,
+            bottom: 0,
+            left: 0,
+            // Snaps, never animates: nothing paints the slot's own width (PanelSizeBox animates the visible resize).
+            width,
+            zIndex: zIndex ?? 0,
+        }, children: children }));
+}
+/**
+ * The element a resize animates: an INNER box, never the slot, which owns `exit` (Motion's docs warn against
+ * `layout` and `exit` on one element). A layout animation sets the real size once and animates a transform
+ * toward it, so the view never re-lays out mid-resize; `layout="size"` because the slot's `x` already animates
+ * position. A view renders it inside its own slot, so a view that never resizes needs no wrapper.
+ * @public
+ */
+export function PanelSizeBox({ width, height, children }) {
+    return (_jsx(motion.div, { "data-panel-size-box": "", layout: "size", transition: PANEL_TRANSITION, style: { width, height }, children: children }));
+}

package/PhoneDetectPrompt.d.ts

@@ -0,0 +1,18 @@
+import * as React from 'react';
+/** @public */
+export interface PhoneDetectPromptProps {
+    /** Non-null exactly once, right after the host first sees a phone-like USB device it has not asked about. */
+    detected: {
+        vendorId: number;
+        productId: number;
+    } | null;
+    onResize: (modelId: string) => void;
+    onDismiss: () => void;
+}
+/**
+ * The one-time "phone connected" notice: a non-blocking toast card, not a modal, with the model picker inline
+ * (the PHONE_MODELS list Settings uses; one click resizes). It renders only the card, un-positioned: the host
+ * places it. No Portal, because a static render (renderToStaticMarkup) has no `document` for one to target.
+ * @public
+ */
+export declare function PhoneDetectPrompt({ detected, onResize, onDismiss }: PhoneDetectPromptProps): React.JSX.Element | null;

package/PhoneDetectPrompt.js

@@ -0,0 +1,52 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+import Box from '@mui/material/Box';
+import Button from '@mui/material/Button';
+import IconButton from '@mui/material/IconButton';
+import Typography from '@mui/material/Typography';
+import CloseIcon from '@mui/icons-material/Close';
+import ExpandMoreIcon from '@mui/icons-material/ExpandMore';
+import SmartphoneIcon from '@mui/icons-material/Smartphone';
+import { PHONE_MODELS, vendorLabelForUsbVendorId } from './phoneModels.js';
+/**
+ * The one-time "phone connected" notice: a non-blocking toast card, not a modal, with the model picker inline
+ * (the PHONE_MODELS list Settings uses; one click resizes). It renders only the card, un-positioned: the host
+ * places it. No Portal, because a static render (renderToStaticMarkup) has no `document` for one to target.
+ * @public
+ */
+export function PhoneDetectPrompt({ detected, onResize, onDismiss }) {
+    const [modelId, setModelId] = useState(PHONE_MODELS[0]?.id ?? 'default');
+    if (!detected)
+        return null;
+    return (_jsxs(Box, { "data-phone-detect-prompt": "", role: "status", "aria-label": "Phone connected", sx: {
+            width: 'max-content',
+            maxWidth: '90vw',
+            display: 'flex',
+            alignItems: 'center',
+            gap: 1,
+            boxSizing: 'border-box',
+            bgcolor: 'background.paper',
+            border: '1px solid',
+            borderColor: 'divider',
+            borderRadius: 2.5,
+            boxShadow: '0 12px 28px rgba(0, 0, 0, 0.45)',
+            px: 1.5,
+            py: 1,
+        }, children: [_jsx(SmartphoneIcon, { fontSize: "small", sx: { color: 'primary.main', flexShrink: 0 } }), _jsx(Typography, { variant: "caption", component: "span", color: "text.secondary", sx: { fontWeight: 600, whiteSpace: 'nowrap' }, children: `${vendorLabelForUsbVendorId(detected.vendorId)} connected` }), _jsxs(Box, { sx: { position: 'relative', display: 'flex', alignItems: 'center' }, children: [_jsx(Box, { component: "select", "data-phone-detect-select": "", "aria-label": "Phone model", value: modelId, onChange: (e) => setModelId(e.target.value), sx: (theme) => ({
+                            width: 240,
+                            boxSizing: 'border-box',
+                            font: 'inherit',
+                            fontSize: theme.typography.caption.fontSize,
+                            py: 0.75,
+                            pl: 1,
+                            pr: 3.5,
+                            borderRadius: 1.5,
+                            border: '1px solid',
+                            borderColor: 'divider',
+                            bgcolor: 'background.default',
+                            color: 'inherit',
+                            appearance: 'none',
+                            WebkitAppearance: 'none',
+                            cursor: 'pointer',
+                        }), children: PHONE_MODELS.map((m) => (_jsx("option", { value: m.id, children: m.label }, m.id))) }), _jsx(ExpandMoreIcon, { fontSize: "small", sx: { position: 'absolute', right: 6, color: 'text.disabled', pointerEvents: 'none' } })] }), _jsx(Button, { size: "small", variant: "contained", disableElevation: true, onClick: () => onResize(modelId), sx: { flexShrink: 0 }, children: "Resize" }), _jsx(IconButton, { size: "small", "aria-label": "Dismiss", onClick: onDismiss, sx: { flexShrink: 0, ml: -0.5 }, children: _jsx(CloseIcon, { fontSize: "small" }) })] }));
+}

package/README.md

@@ -0,0 +1,86 @@
+# phonux
+
+A phone-shaped view host for React: write a view against a small set of host
+APIs, register it, and render it inside one `<HostProvider>`. The host decides
+which views are live; a view never touches the desktop bridge, `localStorage`,
+or anything else app-internal (see `DESIGN.md` in this folder for why).
+
+Install it from npm, together with the peer dependencies listed below:
+
+```sh
+npm install phonux
+```
+
+The package also ships `DESIGN.md`, which explains the design decisions behind
+the API.
+
+## Peer dependencies
+
+phonux does not bundle React, MUI, emotion or motion -- it expects the host
+app to already have them:
+
+```sh
+npm install react react-dom @mui/material @mui/icons-material @emotion/react @emotion/styled motion
+```
+
+## Quickstart
+
+A view reads what it needs from `useHost()` and renders a `<Panel>`:
+
+```tsx
+import { Panel, PanelFrame, useHost, registerView, type ViewProps } from 'phonux';
+
+function MyView({ panel }: ViewProps) {
+  const host = useHost();
+  return (
+    <Panel title={panel.title}>
+      <PanelFrame>{host.device.size.width}px wide</PanelFrame>
+    </Panel>
+  );
+}
+
+registerView('my-view', MyView);
+```
+
+The host mounts one `<HostProvider>`, near the app's root, with its own
+implementation of the host APIs:
+
+```tsx
+import { HostProvider } from 'phonux';
+
+function App({ host }) {
+  return (
+    <HostProvider host={host}>
+      {/* ...the row that resolves and renders registered views... */}
+    </HostProvider>
+  );
+}
+```
+
+## Testing a view
+
+`phonux/testing` exports `createFakeHost()`: a recording fake of every host
+API, so a view can be rendered with no real host behind it.
+
+```tsx
+import { render } from '@testing-library/react';
+import { HostProvider } from 'phonux';
+import { createFakeHost } from 'phonux/testing';
+
+render(
+  <HostProvider host={createFakeHost()}>
+    <MyView panel={{ id: '1', url: 'about:blank', live: true, locked: false }} />
+  </HostProvider>,
+);
+```
+
+`createFakeHost(overrides)` replaces whole members of one API (e.g.
+`{ panels: { panelList: [...] } }`); every call any fake receives is
+recorded, in order, on the returned host's `.calls`.
+
+See `DESIGN.md` in this folder for the reasoning behind the API shape, the
+panel-view registry, and what stays out of a view's reach on purpose.
+
+## Developing phonux
+
+`npm ci`, then `npm run typecheck`, `npm test`, `npm run build`, `npm run check:api-report` and `npm run smoke` (the smoke installs from the registry). DESIGN.md, shipped in the package, covers the design, the release flow and how to try a change in an app before publishing.

package/Workspace.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The workspace shell: the scroll container that holds the centred, animated row, plus the pure
+ * `workspaceShellStyle` derivation behind its centring math (computed synchronously on every render,
+ * never through state or an effect -- see DESIGN.md). The host measures the row itself, before building its
+ * own panels API in the same render, and passes the measurement in as props.
+ */
+import * as React from 'react';
+import { type RefObject } from 'react';
+import { type BoxProps } from '@mui/material/Box';
+import { PANEL_TRANSITION } from './PanelRowSlot.js';
+/** The pure half of the row shell's input: the two measured fields the host's row measurement produces,
+ * flattened here (not a nested `shell` object) so this file never imports a host measurement type.
+ * @internal */
+export interface WorkspaceShellStyleInput {
+    /** The scroll container's measured width. 0 before the first measurement. */
+    containerWidth: number;
+    /** The margin glides once this has held still; it snaps otherwise (see the caller's own settle timer). */
+    rowResizeSettled: boolean;
+    /** The width every fixed column renders at (PhoneDeviceAPI size). */
+    phoneWidth: number;
+    /** The number of always-present columns the row renders. */
+    fixedColumnCount: number;
+    /** Each LIVE panel's own width, in row order (useProvidePanels's `liveWidths`): a parked one is not in the row. */
+    liveWidths: readonly number[];
+}
+/** @internal */
+export interface WorkspaceShellStyle {
+    /** The row's centring margin, px. */
+    marginLeft: number;
+    /** Snap while the container width is still moving, glide once it has held still. */
+    transition: typeof PANEL_TRANSITION | {
+        duration: 0;
+    };
+    /** The scroll container's horizontal overflow -- always 'hidden': the row hides its far panel instead of ever scrolling or growing past what fits. */
+    overflowX: 'hidden';
+}
+/** Everything the markup needs from the measurement, computed synchronously while rendering (never through state or an effect).
+ * @internal */
+export declare function workspaceShellStyle(i: WorkspaceShellStyleInput): WorkspaceShellStyle;
+/** @public */
+export interface WorkspaceProps extends Omit<BoxProps, 'children'> {
+    /** Attach to the scroll container: the caller's ResizeObserver measures it. */
+    overflowContainerRef: RefObject<HTMLDivElement | null>;
+    /** Attach to the row (the flex box holding the columns): the SAME ref object a caller's own
+     * `beforeRow` content may need too, so both centre against the one measured element. */
+    rowRef: RefObject<HTMLDivElement | null>;
+    containerWidth: number;
+    rowResizeSettled: boolean;
+    phoneWidth: number;
+    fixedColumnCount: number;
+    liveWidths: readonly number[];
+    /** Clearance above the row, in px. Defaults to GAP; a host with its own chrome above the scroll container (e.g. a drag strip) passes more. */
+    topPadding?: number;
+    /** Rendered as the scroll container's first child, ahead of the row -- a slot for host content (e.g. a
+     * device toast) that must sit there without being absorbed as row content via `children`. */
+    beforeRow?: React.ReactNode;
+    children: React.ReactNode;
+}
+/**
+ * The workspace shell: a scroll container holding the centred, animated row, with two OverlaySlots
+ * (`dialog` inside the row, `toast` as this component's own last sibling) so a view's WindowOverlay always
+ * has somewhere to render, independent of the host's own mount order.
+ * @public
+ */
+export declare function Workspace(props: WorkspaceProps): React.ReactElement;

package/Workspace.js

@@ -0,0 +1,47 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { motion } from 'motion/react';
+import Box from '@mui/material/Box';
+import { computeRowLayout } from './panelRowLayout.js';
+import { GAP, PANEL_TRANSITION } from './PanelRowSlot.js';
+import { OverlaySlot } from './windowOverlay.js';
+/** Everything the markup needs from the measurement, computed synchronously while rendering (never through state or an effect).
+ * @internal */
+export function workspaceShellStyle(i) {
+    // Calculated from known widths, never measured off the DOM. `fixedColumnCount` and `liveWidths` must come
+    // from the same array the row's JSX renders (see computeRowLayout's own doc comment for why).
+    const { computedRowMarginLeft } = computeRowLayout({
+        containerWidth: i.containerWidth,
+        phoneWidth: i.phoneWidth,
+        gap: GAP,
+        fixedItemCount: i.fixedColumnCount,
+        liveWidths: i.liveWidths,
+    });
+    return {
+        marginLeft: computedRowMarginLeft,
+        transition: i.rowResizeSettled ? PANEL_TRANSITION : { duration: 0 },
+        overflowX: 'hidden',
+    };
+}
+/**
+ * The workspace shell: a scroll container holding the centred, animated row, with two OverlaySlots
+ * (`dialog` inside the row, `toast` as this component's own last sibling) so a view's WindowOverlay always
+ * has somewhere to render, independent of the host's own mount order.
+ * @public
+ */
+export function Workspace(props) {
+    const { overflowContainerRef, rowRef, containerWidth, rowResizeSettled, phoneWidth, fixedColumnCount, liveWidths, topPadding, beforeRow, children, ...rest } = props;
+    const style = workspaceShellStyle({ containerWidth, rowResizeSettled, phoneWidth, fixedColumnCount, liveWidths });
+    return (_jsxs(_Fragment, { children: [_jsxs(Box, { ref: overflowContainerRef, ...rest, sx: {
+                    position: 'relative',
+                    display: 'flex',
+                    height: '100%',
+                    minHeight: 0,
+                    pt: `${topPadding ?? GAP}px`,
+                    pb: `${GAP}px`,
+                    pl: `${GAP}px`,
+                    pr: `${GAP}px`,
+                    // Always hidden: the row hides its far panel instead of ever scrolling or growing past what fits.
+                    overflowX: style.overflowX,
+                    overflowY: 'auto',
+                }, children: [beforeRow, _jsxs(motion.div, { ref: rowRef, style: { display: 'flex', gap: `${GAP}px`, marginTop: 'auto', marginBottom: 'auto', marginRight: 'auto' }, animate: { marginLeft: style.marginLeft }, transition: style.transition, children: [_jsx(OverlaySlot, { name: "dialog" }), children] })] }), _jsx(OverlaySlot, { name: "toast" })] }));
+}

package/defaultTheme.d.ts

@@ -0,0 +1,10 @@
+import { type Theme } from '@mui/material/styles';
+/**
+ * An optional MUI theme for a consumer that embeds phonux views and has no theme of its own; phonux never
+ * applies one implicitly. Wire both: `<ThemeProvider theme={createDefaultTheme(mode)}><CssBaseline />...`.
+ * The no-animation reset lives in MuiCssBaseline's styleOverrides, inert until CssBaseline renders
+ * (https://github.com/mui/material-ui/issues/16483). It touches only `transition`/`animation`: slides write
+ * `transform`/`opacity` directly, so an `!important` on either would freeze them silently. See DESIGN.md.
+ * @public
+ */
+export declare function createDefaultTheme(mode: 'light' | 'dark'): Theme;

package/defaultTheme.js

@@ -0,0 +1,26 @@
+import { createTheme } from '@mui/material/styles';
+/**
+ * An optional MUI theme for a consumer that embeds phonux views and has no theme of its own; phonux never
+ * applies one implicitly. Wire both: `<ThemeProvider theme={createDefaultTheme(mode)}><CssBaseline />...`.
+ * The no-animation reset lives in MuiCssBaseline's styleOverrides, inert until CssBaseline renders
+ * (https://github.com/mui/material-ui/issues/16483). It touches only `transition`/`animation`: slides write
+ * `transform`/`opacity` directly, so an `!important` on either would freeze them silently. See DESIGN.md.
+ * @public
+ */
+export function createDefaultTheme(mode) {
+    return createTheme({
+        palette: { mode },
+        transitions: { create: () => 'none' },
+        components: {
+            MuiCssBaseline: {
+                styleOverrides: {
+                    '*, *::before, *::after': {
+                        transition: 'none !important',
+                        animation: 'none !important',
+                    },
+                },
+            },
+            MuiButtonBase: { defaultProps: { disableRipple: true } },
+        },
+    });
+}

package/directionalTransition.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The enter/exit timing, easing and opacity every animated slot shares, so a live panel and a History row
+ * slide with one feel. A plain function, not a hook: it holds no state and calls no hook, so a test calls it
+ * directly. Why it shares a preset and not the position math: DESIGN.md, "`directionalTransition` and the
+ * test fakes are subpaths, not part of `.`".
+ */
+import type { TargetAndTransition } from 'motion/react';
+/** The one enter/exit timing/easing every animated slot in the app shares. @internal */
+export declare const SLOT_TRANSITION: {
+    duration: number;
+    ease: [number, number, number, number];
+};
+/** @internal */
+export type TransitionAxis = 'x' | 'y';
+/** @internal */
+export interface DirectionalTransition {
+    readonly transition: typeof SLOT_TRANSITION;
+    /** A motion.div's `initial`: `rest + distance` along `axis`, faded out. */
+    readonly initial: TargetAndTransition;
+    /** A motion.div's `animate`: `rest` along `axis`, faded in. */
+    readonly animate: TargetAndTransition;
+    /** The symmetric exit: `rest - distance` along `axis`, faded out. A caller with more than one exit
+     * reason builds its own `exit` and takes only `transition`. */
+    readonly exit: TargetAndTransition;
+}
+/**
+ * Enter/exit values for one card sliding along `axis`. `rest` is its settled position (0 in normal flow, as a
+ * History row; `index * slotWidth` when absolutely positioned, as a live panel). `distance` is how far past
+ * `rest` it starts when entering, and it leaves to the opposite side. It is signed: a positive `distance`
+ * enters from the positive-`axis` side (the right, or below), a negative one from the left, or above.
+ * @internal
+ */
+export declare function directionalTransition(axis: TransitionAxis, rest: number, distance: number): DirectionalTransition;

package/directionalTransition.js

@@ -0,0 +1,24 @@
+/** Seconds, tuned by eye (0.26 read as too fast); one value for every slot, so no copy can drift. */
+const TRANSITION_SEC = 0.4;
+/** Motion wants a cubic-bezier as a fixed 4-tuple, not a plain number[]. */
+const TRANSITION_EASE = [0.2, 0, 0, 1];
+/** The one enter/exit timing/easing every animated slot in the app shares. @internal */
+export const SLOT_TRANSITION = { duration: TRANSITION_SEC, ease: TRANSITION_EASE };
+function withAxis(axis, value, opacity) {
+    return axis === 'x' ? { x: value, opacity } : { y: value, opacity };
+}
+/**
+ * Enter/exit values for one card sliding along `axis`. `rest` is its settled position (0 in normal flow, as a
+ * History row; `index * slotWidth` when absolutely positioned, as a live panel). `distance` is how far past
+ * `rest` it starts when entering, and it leaves to the opposite side. It is signed: a positive `distance`
+ * enters from the positive-`axis` side (the right, or below), a negative one from the left, or above.
+ * @internal
+ */
+export function directionalTransition(axis, rest, distance) {
+    return {
+        transition: SLOT_TRANSITION,
+        initial: withAxis(axis, rest + distance, 0),
+        animate: withAxis(axis, rest, 1),
+        exit: withAxis(axis, rest - distance, 0),
+    };
+}

package/dragToClose.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Drag a view's grab handle DOWN to close it; with `reorder`, also sideways to reorder. It knows nothing about
+ * panels or the app. onClose MUST remove the view: a close never unlocks the scroll ancestors. Also offer a
+ * button calling the same onClose (WCAG 2.5.7). The full contract: DESIGN.md, "`DragToClose`".
+ */
+import * as React from 'react';
+/** The tunables, in one place. Distances in px, velocities in px/s, positive = downward. @public */
+export declare const DRAG_CLOSE: {
+    /** Close once dragged this fraction of the view's height ... */
+    readonly distanceFraction: 0.25;
+    /** ... but never less than this: a click that slips a few px is not a close. */
+    readonly minDistancePx: 80;
+    /** A flick closes early: at least this fast at release ... */
+    readonly flickVelocity: 700;
+    /** ... and at least this far. */
+    readonly flickMinDistancePx: 40;
+    /** Released while moving back UP faster than this (negative): the user changed their mind. */
+    readonly cancelVelocity: -300;
+    /** Seconds the box takes to leave the screen. */
+    readonly exitSeconds: 0.18;
+    readonly snapBack: {
+        readonly type: "spring";
+        readonly stiffness: 520;
+        readonly damping: 42;
+    };
+};
+/** @public */
+export interface ReleaseMeasure {
+    /** How far the box was dragged from its resting place, px (positive = down). */
+    offsetY: number;
+    /** Vertical velocity at release, px/s (positive = down). */
+    velocityY: number;
+    /** The box's own height, px (0 or NaN when unmeasured: only the minimum distance applies). */
+    height: number;
+}
+/** The whole close rule, pure. Never closes on an upward or zero offset, or when released moving back up. @public */
+export declare function shouldCloseOnRelease({ offsetY, velocityY, height }: ReleaseMeasure): boolean;
+/** Spread onto Panel's `grabProps`. @public */
+export interface DragHandleProps {
+    onPointerDown: (event: React.PointerEvent<HTMLElement>) => void;
+    sx: {
+        cursor: 'grab';
+        touchAction: 'pan-x';
+        userSelect: 'none';
+        '&:active': {
+            cursor: 'grabbing';
+        };
+    };
+}
+/** Hands the same handle's horizontal drag to the caller's own reorder (DESIGN.md, "`DragToClose`"). @public */
+export interface ReorderHandle {
+    /** The gesture's own total horizontal offset (px, +right/-left from where the drag started), read once it has locked horizontal AND released. */
+    onDragEnd: (offsetX: number) => void;
+}
+/** @public */
+export declare function DragToClose({ onClose, reorder, children, }: {
+    onClose: () => void;
+    reorder?: ReorderHandle;
+    children: (handle: DragHandleProps) => React.ReactNode;
+}): React.ReactElement;