@phis/ui 0.1.0

package/components/controls/phi-drag-handle-control.d.ts

@@ -0,0 +1,48 @@
+import type { CSSProperties, KeyboardEvent, MouseEvent, PointerEvent, ReactNode, TouchEvent } from "react";
+import type { PhiControlSize } from "../../types/control";
+/**
+ * The grip a node is dragged by.
+ *
+ * Not a button, though it is drawn like one. A button reports a press; a handle hands the pointer and
+ * the keyboard to a drag library, which decides from them when a drag begins, and a plain click on it
+ * does nothing at all. That is why the button Control cannot be it: taking a library's listeners is the
+ * whole job here, and the one thing `PhiButtonControl` refuses on purpose.
+ *
+ * What it takes from the library is named, not passed through. The listeners are the four a sensor can
+ * start a drag from, and anything else a library hands out is dropped rather than spread onto the
+ * element; the attributes are the ones that describe a draggable to assistive technology.
+ */
+type PhiDragHandleListener<TEvent> = (event: TEvent) => void;
+export type PhiDragHandleListeners = {
+    onPointerDown?: PhiDragHandleListener<PointerEvent<HTMLElement>>;
+    onMouseDown?: PhiDragHandleListener<MouseEvent<HTMLElement>>;
+    onTouchStart?: PhiDragHandleListener<TouchEvent<HTMLElement>>;
+    onKeyDown?: PhiDragHandleListener<KeyboardEvent<HTMLElement>>;
+};
+export type PhiDragHandleAttributes = {
+    role?: string;
+    tabIndex?: number;
+    "aria-disabled"?: boolean;
+    "aria-pressed"?: boolean;
+    "aria-roledescription"?: string;
+    "aria-describedby"?: string;
+};
+export type PhiDragHandleControlProps = {
+    ariaLabel: string;
+    /** Registers the handle's element with the drag library; compose it with a ref of your own first. */
+    setActivatorRef: (element: HTMLElement | null) => void;
+    /** The listeners a drag library hands out for its activator; only the four named ones are used. */
+    listeners?: Partial<Record<string, unknown>> | PhiDragHandleListeners;
+    /** The attributes a drag library hands out for its activator; only the named ones are used. */
+    attributes?: Partial<Record<string, unknown>> | PhiDragHandleAttributes;
+    /** Whether the node is on its way; the handle fades so the drop target reads as the focus. */
+    dragging?: boolean;
+    disabled?: boolean;
+    icon?: ReactNode;
+    size?: PhiControlSize;
+    /** A styling hook for chrome that places its affordances by class. */
+    className?: string;
+    style?: CSSProperties;
+};
+export declare function PhiDragHandleControl({ ariaLabel, setActivatorRef, listeners: libraryListeners, attributes: libraryAttributes, dragging, disabled, icon, size, className, style, }: PhiDragHandleControlProps): import("react").JSX.Element;
+export {};

package/components/controls/phi-drag-handle-control.js

@@ -0,0 +1,43 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Button } from "antd";
+import { HolderOutlined } from "@ant-design/icons";
+const PHI_DRAG_HANDLE_LISTENER_KEYS = ["onPointerDown", "onMouseDown", "onTouchStart", "onKeyDown"];
+const PHI_DRAG_HANDLE_ATTRIBUTE_KEYS = [
+    "role",
+    "tabIndex",
+    "aria-disabled",
+    "aria-pressed",
+    "aria-roledescription",
+    "aria-describedby",
+];
+function pick(source, keys) {
+    const picked = {};
+    if (!source)
+        return picked;
+    for (const key of keys) {
+        if (source[key] !== undefined)
+            picked[key] = source[key];
+    }
+    return picked;
+}
+export function PhiDragHandleControl({ ariaLabel, setActivatorRef, listeners: libraryListeners, attributes: libraryAttributes, dragging = false, disabled = false, icon, size = "small", className, style, }) {
+    // Picked by name, then typed by name: the keys are the contract, whatever else the library returned.
+    const listeners = (disabled
+        ? {}
+        : pick(libraryListeners, PHI_DRAG_HANDLE_LISTENER_KEYS));
+    const attributes = pick(libraryAttributes, PHI_DRAG_HANDLE_ATTRIBUTE_KEYS);
+    return (_jsx(Button, { ref: setActivatorRef, className: className, "aria-label": ariaLabel, icon: icon ?? _jsx(HolderOutlined, {}), type: "text", size: size, disabled: disabled, ...attributes, ...listeners, 
+        /*
+         * A click is the end of a drag that never started, and the handle sits on a node that selects on a
+         * press; neither the click nor its default belongs to anything else.
+         */
+        onClick: (event) => {
+            event.preventDefault();
+            event.stopPropagation();
+        }, style: {
+            cursor: disabled ? undefined : dragging ? "grabbing" : "grab",
+            opacity: dragging ? 0.45 : undefined,
+            ...style,
+        } }));
+}

package/components/controls/phi-drawer-control.d.ts

@@ -0,0 +1,11 @@
+import type { PhiCmsOverlayConfig, PhiCmsOverlaySize } from "../../types/cms-overlay";
+import { type PhiOverlayControlCommonProps } from "./phi-overlay-control-contract";
+export type PhiDrawerControlProps = PhiOverlayControlCommonProps & {
+    placement?: PhiCmsOverlayConfig["placement"];
+    size?: PhiCmsOverlaySize;
+    maxSize?: number;
+    resizable?: PhiCmsOverlayConfig["resizable"];
+    push?: PhiCmsOverlayConfig["push"];
+    zIndex?: number;
+};
+export declare function PhiDrawerControl({ open, title, header, body, footer, closable, keyboard, mask, mountPolicy, placement, size, maxSize, resizable, push, zIndex, containerStyle, onDismiss, afterOpenChange, }: PhiDrawerControlProps): import("react").JSX.Element;

package/components/controls/phi-drawer-control.js

@@ -0,0 +1,58 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useSyncExternalStore } from "react";
+import { Drawer } from "antd";
+import { PHI_SPACE } from "../../theme/antd-css-var-contract";
+import { PHI_OVERLAY_DEFAULT_MASK, resolvePhiOverlayDismissSource, resolvePhiOverlayMaskPresentation, } from "./phi-overlay-control-contract";
+const subscribeHydration = () => () => undefined;
+const PHI_DRAWER_HEADER_MIN_BLOCK_SIZE = `calc(var(--ant-control-height) + ${PHI_SPACE.xs} + ${PHI_SPACE.xs})`;
+export function PhiDrawerControl({ open, title, header, body, footer, closable = true, keyboard = true, mask = PHI_OVERLAY_DEFAULT_MASK, mountPolicy = "remount", placement = "right", size, maxSize, resizable = false, push = false, zIndex, containerStyle, onDismiss, afterOpenChange, }) {
+    const hydrated = useSyncExternalStore(subscribeHydration, () => true, () => false);
+    const resolvedMask = resolvePhiOverlayMaskPresentation(mask);
+    const closeAtInlineStart = placement === "right";
+    const renderedTitle = (_jsxs("div", { style: { display: "grid", minBlockSize: PHI_DRAWER_HEADER_MIN_BLOCK_SIZE, minWidth: 0, position: "relative", width: "100%" }, children: [header, title == null ? null : (_jsx("div", { style: { insetInlineStart: PHI_SPACE.lg, minWidth: 0, position: "absolute", top: "50%", transform: "translateY(-50%)", zIndex: 1 }, children: title }))] }));
+    return (_jsx(Drawer, { open: open, title: renderedTitle, closable: closable ? { placement: closeAtInlineStart ? "start" : "end" } : false, keyboard: keyboard, mask: resolvedMask.adapterMask, destroyOnHidden: mountPolicy === "remount", forceRender: hydrated && mountPolicy === "eager", placement: placement, size: size, maxSize: maxSize, resizable: resizable, push: push, zIndex: zIndex, footer: footer ?? null, focusable: { trap: true, focusTriggerAfterClose: true }, styles: {
+            mask: resolvedMask.maskStyle,
+            wrapper: {
+                ...containerStyle,
+                padding: 0,
+            },
+            section: {
+                display: "flex",
+                flexDirection: "column",
+                blockSize: "100%",
+                minBlockSize: 0,
+                maxBlockSize: "100dvh",
+                overflow: "hidden",
+                background: "transparent",
+                borderRadius: "inherit",
+            },
+            header: {
+                flex: "0 0 auto",
+                minBlockSize: PHI_DRAWER_HEADER_MIN_BLOCK_SIZE,
+                position: "relative",
+                padding: 0,
+                background: "transparent",
+            },
+            title: { width: "100%", minWidth: 0 },
+            close: {
+                position: "absolute",
+                top: "50%",
+                left: closeAtInlineStart ? PHI_SPACE.sm : undefined,
+                right: closeAtInlineStart ? undefined : PHI_SPACE.sm,
+                marginInline: 0,
+                transform: "translateY(-50%)",
+                zIndex: 1,
+            },
+            body: {
+                display: "flex",
+                flexDirection: "column",
+                flex: "1 1 auto",
+                minBlockSize: 0,
+                overflowY: "auto",
+                padding: 0,
+                background: "transparent",
+            },
+            footer: { flex: "0 0 auto", padding: 0, background: "transparent" },
+        }, onClose: (event) => onDismiss?.(resolvePhiOverlayDismissSource(event)), afterOpenChange: afterOpenChange, drawerRender: (node) => (_jsx("div", { style: { display: "flex", flexDirection: "column", blockSize: "100%", minBlockSize: 0 }, onMouseDown: (event) => event.stopPropagation(), onClick: (event) => event.stopPropagation(), children: node })), children: body }));
+}

package/components/controls/phi-dropdown-control.d.ts

@@ -0,0 +1,47 @@
+import { type CSSProperties, type ReactElement, type ReactNode, type Ref } from "react";
+import { type PhiMenuControlItem } from "./phi-menu-control";
+export type PhiDropdownControlProps = {
+    items: readonly PhiMenuControlItem[];
+    /**
+     * The entry the surface is currently on. It stays in the list and renders selected; callers
+     * disable it rather than filtering it out, so the trigger never names an absent entry.
+     */
+    selectedKeys?: readonly string[];
+    /** Controlled open state; omit to let the Control own it. */
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /** The trigger element. The Control attaches its press tracking to it. */
+    children: ReactElement<{
+        onMouseDown?: (event: unknown) => void;
+    }>;
+};
+/**
+ * The canonical dropdown menu presentation: this Control owns the Ant Design `Dropdown` primitive
+ * and the trigger mechanics every Phi dropdown shares. Callers describe entries as
+ * `PhiMenuControlItem`s — the same description the navigation menus use — and pass their own trigger
+ * element. A menu that opens from a pill takes `PhiPillDropdownControl` below instead.
+ *
+ * With no entries the trigger renders alone: a dropdown that cannot open must not present itself as
+ * one.
+ */
+export declare function PhiDropdownControl({ items, selectedKeys, open, onOpenChange, children, }: PhiDropdownControlProps): import("react").JSX.Element;
+export type PhiPillDropdownControlProps = Pick<PhiDropdownControlProps, "items" | "selectedKeys" | "open" | "onOpenChange"> & {
+    /** What the trigger names: the entry the surface is on, or the viewer. */
+    label?: ReactNode;
+    /** Stands before the label inside the same trigger, and lights the pill on hover: the account avatar. */
+    leading?: ReactNode;
+    /** `false` sets the label as plain text instead of a pill. */
+    pill?: boolean;
+    /** Shown only while the menu can open. */
+    showChevron?: boolean;
+    /** Hover, focus or press on the trigger -- the moment to fetch what the entries link to. */
+    onIntent?: () => void;
+    triggerRef?: Ref<HTMLButtonElement>;
+    className?: string;
+    style?: CSSProperties;
+};
+/**
+ * The one trigger every pill dropdown uses -- the account, Area and locale menus: a bare button
+ * holding the pill, so hover, border and chevron look the same wherever a menu opens from a pill.
+ */
+export declare function PhiPillDropdownControl({ items, selectedKeys, open, onOpenChange, label, leading, pill, showChevron, onIntent, triggerRef, className, style, }: PhiPillDropdownControlProps): import("react").JSX.Element;

package/components/controls/phi-dropdown-control.js

@@ -0,0 +1,84 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { cloneElement, isValidElement, useCallback, useRef, useState, } from "react";
+import { Dropdown } from "antd";
+import styles from "./phi-dropdown-control.module.css";
+import { toPhiAntdMenuItems } from "./phi-menu-control";
+/**
+ * Ant Design reopens a hover-and-click dropdown when the click that should close it lands on the
+ * trigger: the click reopens what the outside-click already closed. Suppressing the close for this
+ * window is the workaround, and it lives here so it exists exactly once.
+ */
+const PHI_TRIGGER_REOPEN_GUARD_MS = 250;
+/**
+ * The canonical dropdown menu presentation: this Control owns the Ant Design `Dropdown` primitive
+ * and the trigger mechanics every Phi dropdown shares. Callers describe entries as
+ * `PhiMenuControlItem`s — the same description the navigation menus use — and pass their own trigger
+ * element. A menu that opens from a pill takes `PhiPillDropdownControl` below instead.
+ *
+ * With no entries the trigger renders alone: a dropdown that cannot open must not present itself as
+ * one.
+ */
+export function PhiDropdownControl({ items, selectedKeys, open, onOpenChange, children, }) {
+    const [internalOpen, setInternalOpen] = useState(false);
+    const triggerPressAtRef = useRef(0);
+    const resolvedOpen = open ?? internalOpen;
+    const handleTriggerPress = useCallback((event) => {
+        triggerPressAtRef.current = Date.now();
+        return event;
+    }, []);
+    const handleOpenChange = useCallback((nextOpen) => {
+        if (!nextOpen &&
+            resolvedOpen &&
+            Date.now() - triggerPressAtRef.current < PHI_TRIGGER_REOPEN_GUARD_MS) {
+            return;
+        }
+        if (open === undefined) {
+            setInternalOpen(nextOpen);
+        }
+        onOpenChange?.(nextOpen);
+    }, [open, onOpenChange, resolvedOpen]);
+    if (items.length === 0) {
+        return children;
+    }
+    // The press stamp is only ever written from the trigger's mousedown and only ever read from
+    // onOpenChange, both event handlers. The rule cannot see that through cloneElement, which is the
+    // one way to reach the caller's own trigger element without wrapping it in an extra DOM node --
+    // and an extra node would break the popup positioning that measures the trigger.
+    const trigger = isValidElement(children)
+        // eslint-disable-next-line react-hooks/refs
+        ? cloneElement(children, {
+            onMouseDown: (event) => {
+                handleTriggerPress(event);
+                children.props.onMouseDown?.(event);
+            },
+        })
+        : children;
+    return (_jsx(Dropdown, { menu: {
+            items: toPhiAntdMenuItems(items),
+            ...(selectedKeys
+                ? { selectable: true, selectedKeys: [...selectedKeys] }
+                : {}),
+        }, trigger: ["hover", "click"], open: resolvedOpen, onOpenChange: handleOpenChange, children: trigger }));
+}
+/**
+ * The one trigger every pill dropdown uses -- the account, Area and locale menus: a bare button
+ * holding the pill, so hover, border and chevron look the same wherever a menu opens from a pill.
+ */
+export function PhiPillDropdownControl({ items, selectedKeys, open, onOpenChange, label, leading, pill = true, showChevron = true, onIntent, triggerRef, className, style, }) {
+    const canOpen = items.length > 0;
+    const chevron = showChevron && canOpen ? _jsx("span", { className: styles.chevron, "aria-hidden": true }) : null;
+    const hasLabel = label != null && label !== false && label !== "";
+    return (_jsx(PhiDropdownControl, { items: items, selectedKeys: selectedKeys, open: open, onOpenChange: onOpenChange, children: _jsxs("button", { ref: triggerRef, type: "button", className: [styles.trigger, className].filter(Boolean).join(" "), style: {
+                display: "inline-flex",
+                alignItems: "center",
+                gap: 8,
+                fontSize: "inherit",
+                color: "inherit",
+                background: "transparent",
+                border: 0,
+                padding: 0,
+                cursor: canOpen ? "pointer" : "default",
+                ...style,
+            }, "aria-haspopup": canOpen ? "menu" : undefined, onMouseEnter: onIntent, onFocus: onIntent, onClick: onIntent, children: [leading, hasLabel && pill ? (_jsx("span", { className: styles.pillTrigger, children: _jsxs("span", { style: { display: "inline-flex", alignItems: "center", gap: 5 }, children: [_jsx("span", { children: label }), chevron] }) })) : (_jsxs(_Fragment, { children: [hasLabel ? _jsx("span", { children: label }) : null, chevron] }))] }) }));
+}

package/components/controls/phi-dropdown-control.module.css

@@ -0,0 +1,63 @@
+/*
+ * The shared pill trigger: a bordered, fully rounded label that reacts to hover. Hover is a CSS
+ * state, not React state, so a trigger never re-renders to change its own border colour.
+ */
+.pillTrigger {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 3.5rem;
+  padding: 4px 10px;
+  border: 1px solid var(--ant-color-border);
+  border-radius: 999px;
+  color: inherit;
+  font-size: inherit;
+  line-height: 1;
+  text-decoration: none;
+  white-space: nowrap;
+  flex-shrink: 0;
+  transition:
+    color var(--ant-motion-duration-mid),
+    border-color var(--ant-motion-duration-mid);
+}
+
+/* Hovering anywhere on the trigger lights the pill -- the account avatar beside it included. */
+.trigger:hover .pillTrigger {
+  border-color: var(--ant-color-primary-hover);
+  color: var(--ant-color-primary-hover);
+}
+
+/*
+ * The sider menu's submenu arrow, pointing down: antd draws it from two rounded bars sized off the
+ * font size (menu/style: size = fontSize / 7 * 5, bars 0.6 x 0.15 of it, shifted by a quarter), and
+ * an icon glyph never matches it. Centred in its box, so it lines up with the label beside it.
+ */
+.chevron {
+  --phi-chevron-size: calc(var(--ant-font-size) / 7 * 5);
+  position: relative;
+  display: inline-block;
+  flex-shrink: 0;
+  width: var(--phi-chevron-size);
+  height: var(--phi-chevron-size);
+  color: currentcolor;
+}
+
+.chevron::before,
+.chevron::after {
+  position: absolute;
+  top: calc(50% - var(--phi-chevron-size) * 0.075 + var(--phi-chevron-size) * 0.1768);
+  left: calc(50% - var(--phi-chevron-size) * 0.3);
+  width: calc(var(--phi-chevron-size) * 0.6);
+  height: calc(var(--phi-chevron-size) * 0.15);
+  border-radius: var(--ant-border-radius);
+  background-color: currentcolor;
+  content: "";
+}
+
+.chevron::before {
+  transform: rotate(-45deg) translateX(calc(var(--phi-chevron-size) * 0.25));
+}
+
+.chevron::after {
+  transform: rotate(45deg) translateX(calc(var(--phi-chevron-size) * -0.25));
+}

package/components/controls/phi-expand-indicator.d.ts

@@ -0,0 +1,5 @@
+export declare function PhiExpandIndicator({ expanded, animationFromExpanded, onAnimationEnd, }: {
+    expanded: boolean;
+    animationFromExpanded?: boolean;
+    onAnimationEnd?: () => void;
+}): import("react").JSX.Element;

package/components/controls/phi-expand-indicator.js

@@ -0,0 +1,17 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { RightOutlined } from "@ant-design/icons";
+import { usePhiConfig } from "../root/phi-config-provider";
+import styles from "./phi-expand-indicator.module.css";
+export function PhiExpandIndicator({ expanded, animationFromExpanded, onAnimationEnd, }) {
+    const { token } = usePhiConfig();
+    const animated = animationFromExpanded !== undefined;
+    return (_jsx(RightOutlined, { className: animated ? styles.animated : undefined, style: {
+            "--phi-expand-indicator-from": animationFromExpanded ? "90deg" : "0deg",
+            "--phi-expand-indicator-to": expanded ? "90deg" : "0deg",
+            "--phi-expand-indicator-duration": token.motionDurationMid,
+            "--phi-expand-indicator-easing": token.motionEaseInOut,
+            transform: expanded ? "rotate(90deg)" : "rotate(0deg)",
+            transition: `transform ${token.motionDurationMid} ${token.motionEaseInOut}`,
+        }, onAnimationEnd: onAnimationEnd }));
+}

package/components/controls/phi-expand-indicator.module.css

@@ -0,0 +1,16 @@
+@keyframes rotate {
+  from {
+    transform: rotate(var(--phi-expand-indicator-from));
+  }
+
+  to {
+    transform: rotate(var(--phi-expand-indicator-to));
+  }
+}
+
+.animated {
+  animation-duration: var(--phi-expand-indicator-duration);
+  animation-fill-mode: both;
+  animation-name: rotate;
+  animation-timing-function: var(--phi-expand-indicator-easing);
+}

package/components/controls/phi-form-control.d.ts

@@ -0,0 +1,34 @@
+import { type FormInstance } from "antd";
+import type { PhiFormDescriptor } from "../../types/form-descriptor";
+import type { PhiFormProviderRegistry } from "../forms/form-provider-registry";
+export type PhiFormControlProps = {
+    descriptor: PhiFormDescriptor;
+    registry?: PhiFormProviderRegistry;
+    labels?: Readonly<Record<string, string>>;
+    /** What the Widget was placed with, for text a field takes from its placement rather than its form. */
+    formConfig?: Readonly<Record<string, unknown>>;
+    initialValues?: Record<string, unknown>;
+    disabled?: boolean;
+    readOnly?: boolean;
+    conditionControllerStates?: Readonly<Record<string, Record<string, unknown>>>;
+    form?: PhiFormControlFormInstance;
+    onValuesChange?: (changedValues: Record<string, unknown>, allValues: Record<string, unknown>) => void;
+    onSubmit: (values: Record<string, unknown>) => void | Promise<void>;
+    onSubmittingChange?: (submitting: boolean) => void;
+    onValidationFailed?: (value: {
+        valid: false;
+        errors: Record<string, readonly string[]>;
+    }) => void;
+    onFormReady?: (form: PhiFormControlFormInstance) => void;
+    onStateChange?: (state: {
+        dirty: boolean;
+        valid: boolean;
+    }) => void;
+    onBlurCapture?: () => void;
+};
+export type PhiFormControlFormInstance = FormInstance<Record<string, unknown>>;
+export type PhiFormControlHandle = {
+    submit(): void;
+    reset(): void;
+};
+export declare const PhiFormControl: import("react").ForwardRefExoticComponent<PhiFormControlProps & import("react").RefAttributes<PhiFormControlHandle>>;