@intentface/ui 0.0.0 → 0.7.0

package/dist/internal/render/useRenderElement.d.ts

@@ -0,0 +1,62 @@
+import * as React from 'react';
+import type { ComponentRenderFn, HTMLProps } from './types.js';
+import type { WithDataAttributes } from './baseTypes.js';
+import { type StateAttributesMapping } from './getStateAttributesProps.js';
+type IntrinsicTagName = keyof React.JSX.IntrinsicElements;
+/**
+ * Renders a primitive part's element.
+ *
+ * @param element The default HTML element to render. Can be overridden by the `render` prop.
+ * @param componentProps An object containing the `render` and `className` props to be used for element customization. Other props are ignored.
+ * @param params Additional parameters for rendering the element.
+ */
+export declare function useRenderElement<State extends Record<string, any>, RenderedElementType extends Element, TagName extends IntrinsicTagName | undefined, Enabled extends boolean | undefined = undefined>(element: TagName, componentProps: UseRenderElementComponentProps<State>, params?: UseRenderElementParameters<State, RenderedElementType, TagName, Enabled>): Enabled extends false ? null : React.ReactElement;
+type RenderFunctionProps<TagName> = TagName extends keyof React.JSX.IntrinsicElements ? React.JSX.IntrinsicElements[TagName] : React.HTMLAttributes<any>;
+export type UseRenderElementParameters<State, RenderedElementType extends Element, TagName, Enabled extends boolean | undefined> = {
+    /**
+     * If `false`, the hook will skip most of its internal logic and return `null`.
+     * This is useful for rendering a component conditionally.
+     * @default true
+     */
+    enabled?: Enabled | undefined;
+    /**
+     * @deprecated
+     */
+    propGetter?: ((externalProps: HTMLProps) => HTMLProps) | undefined;
+    /**
+     * The ref to apply to the rendered element.
+     */
+    ref?: React.Ref<RenderedElementType> | (React.Ref<RenderedElementType> | undefined)[] | undefined;
+    /**
+     * The state of the component.
+     */
+    state?: State | undefined;
+    /**
+     * Intrinsic props to be spread on the rendered element. Accepts bespoke
+     * data-* part attributes in plain object literals (WithDataAttributes).
+     */
+    props?: WithDataAttributes<RenderFunctionProps<TagName>> | Array<WithDataAttributes<RenderFunctionProps<TagName>> | undefined | ((props: RenderFunctionProps<TagName>) => RenderFunctionProps<TagName>)> | undefined;
+    /**
+     * A mapping of state to `data-*` attributes.
+     */
+    stateAttributesMapping?: StateAttributesMapping<State> | undefined;
+};
+export interface UseRenderElementComponentProps<State> {
+    /**
+     * The class name to apply to the rendered element.
+     * Can be a string or a function that accepts the state and returns a string.
+     */
+    className?: string | ((state: State) => string | undefined) | undefined;
+    /**
+     * The render prop or React element to override the default element.
+     */
+    render?: undefined | React.ReactElement | ComponentRenderFn<React.HTMLAttributes<any>, State>;
+    /**
+     * The style to apply to the rendered element.
+     * Can be a style object or a function that accepts the state and returns a style object.
+     */
+    style?: React.CSSProperties | ((state: State) => React.CSSProperties | undefined) | undefined;
+}
+export interface UseRenderElementState {
+}
+export {};

package/dist/internal/render/useRenderElement.js

@@ -0,0 +1,157 @@
+import { createElement as _createElement } from "react";
+// Vendored from @base-ui/react v1.6.0 (MIT) — packages/react/src/internals/useRenderElement.tsx
+// https://github.com/mui/base-ui — import specifiers rewired, names and messages made neutral; one local departure:
+// the `props` config accepts bespoke data-* part attributes (WithDataAttributes).
+import * as React from 'react';
+import { useMergedRefs, useMergedRefsN } from './useMergedRefs.js';
+import { getReactElementRef } from './getReactElementRef.js';
+import { mergeObjects } from './mergeObjects.js';
+import { warn } from './warn.js';
+import { EMPTY_OBJECT } from './empty.js';
+import { getStateAttributesProps } from './getStateAttributesProps.js';
+import { resolveClassName } from './resolveClassName.js';
+import { resolveStyle } from './resolveStyle.js';
+import { mergeProps, mergePropsN, mergeClassNames } from './mergeProps.js';
+/**
+ * Renders a primitive part's element.
+ *
+ * @param element The default HTML element to render. Can be overridden by the `render` prop.
+ * @param componentProps An object containing the `render` and `className` props to be used for element customization. Other props are ignored.
+ * @param params Additional parameters for rendering the element.
+ */
+export function useRenderElement(element, componentProps, params = {}) {
+    const renderProp = componentProps.render;
+    const outProps = useRenderElementProps(componentProps, params);
+    if (params.enabled === false) {
+        return null;
+    }
+    const state = params.state ?? EMPTY_OBJECT;
+    return evaluateRenderProp(element, renderProp, outProps, state);
+}
+/**
+ * Computes render element final props.
+ */
+function useRenderElementProps(componentProps, params = {}) {
+    const { className: classNameProp, style: styleProp, render: renderProp } = componentProps;
+    const { state = EMPTY_OBJECT, ref, props, stateAttributesMapping, enabled = true, } = params;
+    const className = enabled ? resolveClassName(classNameProp, state) : undefined;
+    const style = enabled ? resolveStyle(styleProp, state) : undefined;
+    const stateProps = enabled
+        ? getStateAttributesProps(state, stateAttributesMapping)
+        : EMPTY_OBJECT;
+    const resolvedProps = enabled && props ? resolveRenderFunctionProps(props) : undefined;
+    // Ensure outProps is always a new mutable object when enabled, never EMPTY_OBJECT.
+    // This prevents potential TypeError when setting ref, className, or style properties,
+    // since EMPTY_OBJECT is frozen and mutations would fail in strict mode.
+    const outProps = enabled
+        ? (mergeObjects(stateProps, resolvedProps) ?? {})
+        : EMPTY_OBJECT;
+    // SAFETY: The `useMergedRefs` functions use a single hook to store the same value,
+    // switching between them at runtime is safe. If this assertion fails, React will
+    // throw at runtime anyway.
+    // This also skips the `useMergedRefs` call on the server, which is fine because
+    // refs are not used on the server side.
+    /* eslint-disable react-hooks/rules-of-hooks */
+    if (typeof document !== 'undefined') {
+        if (!enabled) {
+            useMergedRefs(null, null);
+        }
+        else if (Array.isArray(ref)) {
+            outProps.ref = useMergedRefsN([outProps.ref, getReactElementRef(renderProp), ...ref]);
+        }
+        else {
+            outProps.ref = useMergedRefs(outProps.ref, getReactElementRef(renderProp), ref);
+        }
+    }
+    if (!enabled) {
+        return EMPTY_OBJECT;
+    }
+    if (className !== undefined) {
+        outProps.className = mergeClassNames(outProps.className, className);
+    }
+    if (style !== undefined) {
+        outProps.style = mergeObjects(outProps.style, style);
+    }
+    return outProps;
+}
+function resolveRenderFunctionProps(props) {
+    if (Array.isArray(props)) {
+        return mergePropsN(props);
+    }
+    return mergeProps(undefined, props);
+}
+// The symbol React uses internally for lazy components
+// https://github.com/facebook/react/blob/a0566250b210499b4c5677f5ac2eedbd71d51a1b/packages/shared/ReactSymbols.js#L31
+//
+// TODO delete once https://github.com/facebook/react/issues/32392 is fixed
+const REACT_LAZY_TYPE = Symbol.for('react.lazy');
+const COMPONENT_IDENTIFIER_PATTERN = /^[A-Z][A-Za-z0-9$]*$/;
+const LOWERCASE_CHARACTER_PATTERN = /[a-z]/;
+function evaluateRenderProp(element, render, props, state) {
+    if (render) {
+        if (typeof render === 'function') {
+            if (process.env.NODE_ENV !== 'production') {
+                warnIfRenderPropLooksLikeComponent(render);
+            }
+            return render(props, state);
+        }
+        const mergedProps = mergeProps(props, render.props);
+        mergedProps.ref = props.ref;
+        let newElement = render;
+        // Workaround for https://github.com/facebook/react/issues/32392
+        // This works because the toArray() logic unwrap lazy element type in
+        // https://github.com/facebook/react/blob/a0566250b210499b4c5677f5ac2eedbd71d51a1b/packages/react/src/ReactChildren.js#L186
+        if (newElement?.$$typeof === REACT_LAZY_TYPE) {
+            const children = React.Children.toArray(render);
+            newElement = children[0];
+        }
+        // There is a high number of indirections, the error message thrown by React.cloneElement() is
+        // hard to use for developers, this logic provides a better context.
+        //
+        // Our general guideline is to never change the control flow depending on the environment.
+        // However, React.cloneElement() throws if React.isValidElement() is false,
+        // so we can throw before with custom message.
+        if (process.env.NODE_ENV !== 'production') {
+            if (!React.isValidElement(newElement)) {
+                // TODO: fix mui/no-guarded-throw
+                // eslint-disable-next-line mui/no-guarded-throw
+                throw new Error([
+                    '@intentface/ui: The `render` prop was provided an invalid React element as `React.isValidElement(render)` is `false`.',
+                    'A valid React element must be provided to the `render` prop because it is cloned with props to replace the default element.',
+                    'https://ui.intentface.com/handbook/composition',
+                ].join('\n'));
+            }
+        }
+        return React.cloneElement(newElement, mergedProps);
+    }
+    if (element) {
+        if (typeof element === 'string') {
+            return renderTag(element, props);
+        }
+    }
+    // Unreachable, but the typings on `useRenderElement` need to be reworked
+    // to annotate it correctly.
+    throw new Error('@intentface/ui: Render element or function are not defined.');
+}
+function warnIfRenderPropLooksLikeComponent(renderFn) {
+    const functionName = renderFn.name;
+    if (functionName.length === 0) {
+        return;
+    }
+    if (!COMPONENT_IDENTIFIER_PATTERN.test(functionName)) {
+        return;
+    }
+    if (!LOWERCASE_CHARACTER_PATTERN.test(functionName)) {
+        return;
+    }
+    warn(`The \`render\` prop received a function named \`${functionName}\` that starts with an uppercase letter.`, 'This usually means a React component was passed directly as `render={Component}`.', 'The part calls `render` as a plain function, which can break the Rules of Hooks during reconciliation.', 'If this is an intentional render callback, rename it to start with a lowercase letter.', 'Use `render={<Component />}` or `render={(props) => <Component {...props} />}` instead.', 'https://ui.intentface.com/handbook/composition');
+}
+function renderTag(Tag, props) {
+    if (Tag === 'button') {
+        return _createElement("button", { type: "button", ...props, key: props.key });
+    }
+    if (Tag === 'img') {
+        return _createElement("img", { alt: "", ...props, key: props.key });
+    }
+    return React.createElement(Tag, props);
+}

package/dist/internal/render/warn.d.ts

@@ -0,0 +1 @@
+export declare function warn(...messages: string[]): void;

package/dist/internal/render/warn.js

@@ -0,0 +1,15 @@
+// Vendored from @base-ui/utils v1.6.0 (MIT) — packages/utils/src/warn.ts
+// https://github.com/mui/base-ui — exact copy apart from the message prefix.
+let set;
+if (process.env.NODE_ENV !== 'production') {
+    set = new Set();
+}
+export function warn(...messages) {
+    if (process.env.NODE_ENV !== 'production') {
+        const messageKey = messages.join(' ');
+        if (!set.has(messageKey)) {
+            set.add(messageKey);
+            console.warn(`@intentface/ui: ${messageKey}`);
+        }
+    }
+}

package/dist/internal/safe-polygon.d.ts

@@ -0,0 +1,21 @@
+export type Side = "top" | "right" | "bottom" | "left";
+export type SafePolygonOptions = {
+    /** Where the mouse left the reference. */
+    x: number;
+    y: number;
+    /** Which side of the reference the floating element sits on. */
+    side: Side;
+    reference: Element;
+    floating: Element;
+    /** Called once the mouse leaves the safe area. */
+    onClose: () => void;
+};
+/**
+ * The prediction cone: keeps a floating element open while the mouse travels
+ * from its reference towards it. `onMouseMove` listens on the document and calls
+ * `onClose` once the mouse leaves the safe area; `stop` cancels a pending check.
+ */
+export declare const createSafePolygon: ({ x, y, side, reference, floating, onClose, }: SafePolygonOptions) => {
+    onMouseMove: (event: MouseEvent) => void;
+    stop: () => void;
+};

package/dist/internal/safe-polygon.js

@@ -0,0 +1,179 @@
+// Adapted from @floating-ui/react v0.27.20 (MIT) — packages/react/src/safePolygon.ts
+// https://github.com/floating-ui/floating-ui — the same geometry, trimmed to one
+// floating element with no nested tree, and typed to the fields it reads.
+const BUFFER = 0.5;
+/** Slower than this, in px per ms, the mouse has stopped heading anywhere. */
+const INTENT_SPEED = 0.1;
+/** How long a mouse inside the cone may take to land before it counts as gone. */
+const LANDING_TIMEOUT = 40;
+const isPointInPolygon = ([x, y], polygon) => {
+    let inside = false;
+    for (let index = 0, previous = polygon.length - 1; index < polygon.length; previous = index++) {
+        const [currentX, currentY] = polygon[index] ?? [0, 0];
+        const [previousX, previousY] = polygon[previous] ?? [0, 0];
+        const crosses = currentY >= y !== previousY >= y &&
+            x <= ((previousX - currentX) * (y - currentY)) / (previousY - currentY) + currentX;
+        if (crosses)
+            inside = !inside;
+    }
+    return inside;
+};
+const isInsideRect = ([x, y], rect) => x >= rect.x && x <= rect.x + rect.width && y >= rect.y && y <= rect.y + rect.height;
+const contains = (parent, target) => target instanceof Node && parent.contains(target);
+/** The rectangular gap between the two elements, which always counts as safe. */
+const troughBetween = (side, reference, floating) => {
+    const floatingWider = floating.width > reference.width;
+    const floatingTaller = floating.height > reference.height;
+    const left = (floatingWider ? reference : floating).left;
+    const right = (floatingWider ? reference : floating).right;
+    const top = (floatingTaller ? reference : floating).top;
+    const bottom = (floatingTaller ? reference : floating).bottom;
+    switch (side) {
+        case "top":
+            return [
+                [left, reference.top + 1],
+                [left, floating.bottom - 1],
+                [right, floating.bottom - 1],
+                [right, reference.top + 1],
+            ];
+        case "bottom":
+            return [
+                [left, floating.top + 1],
+                [left, reference.bottom - 1],
+                [right, reference.bottom - 1],
+                [right, floating.top + 1],
+            ];
+        case "left":
+            return [
+                [floating.right - 1, bottom],
+                [floating.right - 1, top],
+                [reference.left + 1, top],
+                [reference.left + 1, bottom],
+            ];
+        case "right":
+            return [
+                [reference.right - 1, bottom],
+                [reference.right - 1, top],
+                [floating.left + 1, top],
+                [floating.left + 1, bottom],
+            ];
+    }
+};
+/** The triangle from where the mouse left to the near edge of the floating element. */
+const coneFrom = ([x, y], side, reference, floating) => {
+    const floatingWider = floating.width > reference.width;
+    const floatingTaller = floating.height > reference.height;
+    const leftFromRight = x > floating.right - floating.width / 2;
+    const leftFromBottom = y > floating.bottom - floating.height / 2;
+    // Two points either side of the cursor, so the triangle has a base to start from.
+    const acrossX = (spread) => floatingWider ? x + (spread * BUFFER) / 2 : leftFromRight ? x + BUFFER * 4 : x - BUFFER * 4;
+    const acrossY = (spread) => floatingTaller ? y + (spread * BUFFER) / 2 : leftFromBottom ? y + BUFFER * 4 : y - BUFFER * 4;
+    switch (side) {
+        case "top": {
+            const nearEdge = floating.bottom - BUFFER;
+            return [
+                [acrossX(1), y + BUFFER + 1],
+                [acrossX(-1), y + BUFFER + 1],
+                [floating.left, leftFromRight || floatingWider ? nearEdge : floating.top],
+                [floating.right, leftFromRight ? (floatingWider ? nearEdge : floating.top) : nearEdge],
+            ];
+        }
+        case "bottom": {
+            const nearEdge = floating.top + BUFFER;
+            return [
+                [acrossX(1), y - BUFFER],
+                [acrossX(-1), y - BUFFER],
+                [floating.left, leftFromRight || floatingWider ? nearEdge : floating.bottom],
+                [floating.right, leftFromRight ? (floatingWider ? nearEdge : floating.bottom) : nearEdge],
+            ];
+        }
+        case "left": {
+            const nearEdge = floating.right - BUFFER;
+            return [
+                [leftFromBottom || floatingTaller ? nearEdge : floating.left, floating.top],
+                [leftFromBottom ? (floatingTaller ? nearEdge : floating.left) : nearEdge, floating.bottom],
+                [x + BUFFER + 1, acrossY(1)],
+                [x + BUFFER + 1, acrossY(-1)],
+            ];
+        }
+        case "right": {
+            const nearEdge = floating.left + BUFFER;
+            return [
+                [x - BUFFER, acrossY(1)],
+                [x - BUFFER, acrossY(-1)],
+                [leftFromBottom || floatingTaller ? nearEdge : floating.right, floating.top],
+                [leftFromBottom ? (floatingTaller ? nearEdge : floating.right) : nearEdge, floating.bottom],
+            ];
+        }
+    }
+};
+/**
+ * The prediction cone: keeps a floating element open while the mouse travels
+ * from its reference towards it. `onMouseMove` listens on the document and calls
+ * `onClose` once the mouse leaves the safe area; `stop` cancels a pending check.
+ */
+export const createSafePolygon = ({ x, y, side, reference, floating, onClose, }) => {
+    let landingTimer;
+    let hasLanded = false;
+    let lastPoint = null;
+    let lastTime = performance.now();
+    const speedTo = ([pointX, pointY]) => {
+        const now = performance.now();
+        const elapsed = now - lastTime;
+        const previous = lastPoint;
+        lastPoint = [pointX, pointY];
+        lastTime = now;
+        if (!previous || elapsed === 0)
+            return null;
+        return Math.hypot(pointX - previous[0], pointY - previous[1]) / elapsed;
+    };
+    const close = () => {
+        clearTimeout(landingTimer);
+        onClose();
+    };
+    const onMouseMove = (event) => {
+        clearTimeout(landingTimer);
+        const point = [event.clientX, event.clientY];
+        const target = event.composedPath?.()[0] ?? event.target;
+        const leaving = event.type === "mouseleave";
+        const overFloating = contains(floating, target);
+        const overReference = contains(reference, target);
+        const referenceRect = reference.getBoundingClientRect();
+        const floatingRect = floating.getBoundingClientRect();
+        if (overFloating) {
+            hasLanded = true;
+            if (!leaving)
+                return;
+        }
+        if (overReference)
+            hasLanded = false;
+        if (overReference && !leaving) {
+            hasLanded = true;
+            return;
+        }
+        // An overlapping floating element would otherwise loop between open and closed.
+        if (leaving && contains(floating, event.relatedTarget))
+            return;
+        // Leaving from the far side; the buffer would otherwise keep it open. 1px covers rounding.
+        const leftFromFarSide = (side === "top" && y >= referenceRect.bottom - 1) ||
+            (side === "bottom" && y <= referenceRect.top + 1) ||
+            (side === "left" && x >= referenceRect.right - 1) ||
+            (side === "right" && x <= referenceRect.left + 1);
+        if (leftFromFarSide)
+            return close();
+        if (isPointInPolygon(point, troughBetween(side, referenceRect, floatingRect)))
+            return;
+        if (hasLanded && !isInsideRect(point, referenceRect))
+            return close();
+        if (!leaving) {
+            const speed = speedTo(point);
+            if (speed !== null && speed < INTENT_SPEED)
+                return close();
+        }
+        if (!isPointInPolygon(point, coneFrom([x, y], side, referenceRect, floatingRect)))
+            close();
+        else if (!hasLanded)
+            landingTimer = setTimeout(close, LANDING_TIMEOUT);
+    };
+    return { onMouseMove, stop: () => clearTimeout(landingTimer) };
+};

package/dist/internal/scroll-into-view-within.d.ts

@@ -0,0 +1 @@
+export declare const scrollIntoViewWithin: (rect: DOMRect, from: HTMLElement, boundary: Element) => void;

package/dist/internal/scroll-into-view-within.js

@@ -0,0 +1,26 @@
+// Bring a rect into view by scrolling each scrollable ancestor of `from` just
+// enough — but never one outside `boundary`. A primitive scrolls only its own
+// scroll areas: walking further would reach the page around it (an embedded
+// composer's docs page, say) and yank it, which is exactly what scrollIntoView
+// does and why it isn't used. `boundary` itself may scroll.
+export const scrollIntoViewWithin = (rect, from, boundary) => {
+    let { top, bottom } = rect;
+    let scroller = from;
+    while (scroller && boundary.contains(scroller)) {
+        const { overflowY } = getComputedStyle(scroller);
+        if ((overflowY === "auto" || overflowY === "scroll") &&
+            scroller.scrollHeight > scroller.clientHeight) {
+            const view = scroller.getBoundingClientRect();
+            const before = scroller.scrollTop;
+            if (top < view.top)
+                scroller.scrollTop -= view.top - top;
+            else if (bottom > view.bottom)
+                scroller.scrollTop += bottom - view.bottom;
+            // The rect moves with the scrolled content; carry that to the next scroller out.
+            const moved = scroller.scrollTop - before;
+            top -= moved;
+            bottom -= moved;
+        }
+        scroller = scroller.parentElement;
+    }
+};

package/dist/internal/standard-schema.d.ts

@@ -0,0 +1,38 @@
+/** One problem found by a validator. */
+export type StandardIssue = {
+    readonly message: string;
+    readonly path?: ReadonlyArray<PropertyKey | {
+        readonly key: PropertyKey;
+    }> | undefined;
+};
+type StandardResult<Output> = {
+    readonly value: Output;
+    readonly issues?: undefined;
+} | {
+    readonly issues: ReadonlyArray<StandardIssue>;
+};
+/** A schema that validates: zod, Valibot, ArkType and others implement it. */
+export type StandardSchema<Input = unknown, Output = Input> = {
+    readonly "~standard": {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => StandardResult<Output> | Promise<StandardResult<Output>>;
+        readonly types?: {
+            readonly input: Input;
+            readonly output: Output;
+        } | undefined;
+    };
+};
+/** A schema that can describe itself as JSON Schema (zod 4.2+, ArkType 2.1.28+, Valibot 1.2+). */
+export type StandardJSONSchema = {
+    readonly "~standard": {
+        readonly jsonSchema: {
+            readonly input: (options: {
+                readonly target: string;
+            }) => Record<string, unknown>;
+        };
+    };
+};
+export type InferOutput<Schema extends StandardSchema> = NonNullable<Schema["~standard"]["types"]>["output"];
+export type InferInput<Schema extends StandardSchema> = NonNullable<Schema["~standard"]["types"]>["input"];
+export {};

package/dist/internal/standard-schema.js

@@ -0,0 +1,4 @@
+// The parts of the Standard Schema and Standard JSON Schema specs this package
+// reads (https://standardschema.dev), restated as structural types so any
+// compliant validator fits without a dependency. MIT, Standard Schema authors.
+export {};

package/dist/internal/state-mappings.d.ts

@@ -0,0 +1,8 @@
+import type { StateAttributesMapping } from "./render/getStateAttributesProps.js";
+import type { TransitionStatus } from "./render/transition.js";
+export declare const openStateMapping: StateAttributesMapping<{
+    open: boolean;
+}>;
+export declare const transitionStatusMapping: StateAttributesMapping<{
+    transitionStatus: TransitionStatus;
+}>;

package/dist/internal/state-mappings.js

@@ -0,0 +1,17 @@
+// Shared state → data-attribute mappings for useRenderElement. Base UI
+// convention: `open` produces a data-open / data-closed presence pair so both
+// directions are styleable (exit transitions target data-closed).
+export const openStateMapping = {
+    open: (value) => (value ? { "data-open": "" } : { "data-closed": "" }),
+};
+// Base UI convention: the transitional frames of an open/close animation surface as
+// data-starting-style (entering) / data-ending-style (exiting); settled states emit nothing.
+export const transitionStatusMapping = {
+    transitionStatus: (value) => {
+        if (value === "starting")
+            return { "data-starting-style": "" };
+        if (value === "ending")
+            return { "data-ending-style": "" };
+        return null;
+    },
+};

package/dist/internal/use-controlled.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Controlled/uncontrolled state, decided once.
+ *
+ * Whether a component is controlled is latched on the first render and never
+ * re-read. A component that flipped mid-life would silently drop state, so in
+ * development the flip is reported — loudly, but without throwing, since a
+ * render-time throw makes the very UI you need to inspect disappear.
+ *
+ * The setter is a no-op while controlled: whoever owns `value` is the only
+ * thing that can change it.
+ */
+export declare const useControlled: <Value>({ controlled, default: defaultValue, name, state, }: {
+    controlled: Value | undefined;
+    default: Value;
+    /** Component name, for the development warning. */
+    name: string;
+    /** Prop name, for the development warning. */
+    state?: string;
+}) => readonly [Value, (next: Value) => void];

package/dist/internal/use-controlled.js

@@ -0,0 +1,33 @@
+"use client";
+import { useCallback, useRef, useState } from "react";
+/**
+ * Controlled/uncontrolled state, decided once.
+ *
+ * Whether a component is controlled is latched on the first render and never
+ * re-read. A component that flipped mid-life would silently drop state, so in
+ * development the flip is reported — loudly, but without throwing, since a
+ * render-time throw makes the very UI you need to inspect disappear.
+ *
+ * The setter is a no-op while controlled: whoever owns `value` is the only
+ * thing that can change it.
+ */
+export const useControlled = ({ controlled, default: defaultValue, name, state = "value", }) => {
+    const isControlledRef = useRef(controlled !== undefined);
+    const isControlled = isControlledRef.current;
+    const [uncontrolledValue, setUncontrolledValue] = useState(defaultValue);
+    if (process.env.NODE_ENV !== "production" && isControlled !== (controlled !== undefined)) {
+        console.error(`[@intentface/ui] ${name} is switching between controlled and uncontrolled for \`${state}\`. ` +
+            "Pick one for the component's lifetime: pass the prop always, or never.");
+    }
+    // Reads the ref rather than the destructured value, so the dependency list is
+    // genuinely empty and the setter's identity never changes.
+    const setValueIfUncontrolled = useCallback((next) => {
+        if (isControlledRef.current)
+            return;
+        setUncontrolledValue(next);
+    }, []);
+    return [
+        isControlled ? controlled : uncontrolledValue,
+        setValueIfUncontrolled,
+    ];
+};

package/dist/message/index.d.ts

@@ -0,0 +1,3 @@
+export * as Message from "./index.parts.js";
+export type { MessageChipSegment, MessageRootProps, MessageSelection, MessageState, MessageTextProps, MessageTurnProps, } from "./message.js";
+export { readMessageSelection, useMessageSelection, useMessageSelectionScope, } from "./message.js";

package/dist/message/index.js

@@ -0,0 +1,3 @@
+// Public surface of @intentface/ui/message. No directive — see index.parts.ts.
+export * as Message from "./index.parts.js";
+export { readMessageSelection, useMessageSelection, useMessageSelectionScope, } from "./message.js";

package/dist/message/index.parts.d.ts

@@ -0,0 +1 @@
+export { MessageRoot as Root, MessageText as Text, MessageTurn as Turn, } from "./message.js";

package/dist/message/index.parts.js

@@ -0,0 +1,5 @@
+// Part names for the `Message` namespace. Deliberately carries no
+// "use client" directive: this module and index.ts must stay server-resolvable
+// so a React Server Component can reach Message.Root and its siblings
+// through them. The directive lives one level down, on message.tsx.
+export { MessageRoot as Root, MessageText as Text, MessageTurn as Turn, } from "./message.js";