@pibbl/core 0.0.1

package/dist/lib/layout/positioning-diagnostics.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/lib/layout/positioning-diagnostics.ts"],
+  "sourcesContent": ["import { isDevelopment } from '../development.js';\nimport { getElementSource } from '../element/metadata.js';\nimport type { PibblElement } from '../element/types.js';\nimport type { SystemStyle } from '../types.js';\n\nexport function assertSupportedChildPosition(layout: string, child: PibblElement<any>, style: Readonly<SystemStyle>): void {\n  if (!isDevelopment) return;\n  const values = style as Readonly<Record<string, unknown>>;\n  const fields = (['left', 'top'] as const).filter(key => Object.prototype.hasOwnProperty.call(values, key) && values[key] !== undefined);\n  if (fields.length === 0) return;\n  const source = getElementSource(child);\n  const location = source ? ` Source: ${source.fileName}:${source.lineNumber}` : '';\n  throw new Error(`PIBBL_LAYOUT_IGNORED_POSITION: ${child.type.name || 'Anonymous'} inside ${layout} declares ${fields.map(key => `${key}: ${String(values[key])}`).join(', ')}. ${layout} controls this child's position; these fields have no effect. Use ${layout} alignment/gap or an Absolute region for positioned content.${location}`);\n}\n"],
+  "mappings": "AAAA,SAAS,qBAAqB;AAC9B,SAAS,wBAAwB;AAI1B,SAAS,6BAA6B,QAAgB,OAA0B,OAAoC;AACzH,MAAI,CAAC,cAAe;AACpB,QAAM,SAAS;AACf,QAAM,SAAU,CAAC,QAAQ,KAAK,EAAY,OAAO,SAAO,OAAO,UAAU,eAAe,KAAK,QAAQ,GAAG,KAAK,OAAO,GAAG,MAAM,MAAS;AACtI,MAAI,OAAO,WAAW,EAAG;AACzB,QAAM,SAAS,iBAAiB,KAAK;AACrC,QAAM,WAAW,SAAS,YAAY,OAAO,QAAQ,IAAI,OAAO,UAAU,KAAK;AAC/E,QAAM,IAAI,MAAM,kCAAkC,MAAM,KAAK,QAAQ,WAAW,WAAW,MAAM,aAAa,OAAO,IAAI,SAAO,GAAG,GAAG,KAAK,OAAO,OAAO,GAAG,CAAC,CAAC,EAAE,EAAE,KAAK,IAAI,CAAC,KAAK,MAAM,qEAAqE,MAAM,+DAA+D,QAAQ,EAAE;AAC7U;",
+  "names": []
+}

package/dist/lib/layout/types.d.ts

@@ -0,0 +1,78 @@
+import type { measureElement } from "./measure.js";
+import type { resolveBox } from "./box.js";
+import type { LayoutDiagnosticContext } from "../style/diagnostics.js";
+import type { normalizeEdges } from "../style/normalize.js";
+import type { BoxStyle, ResolvedBoxStyle } from "../style/types.js";
+import type { PibblRenderLayerTarget } from "../render-layer/types.js";
+import type { useLayoutBox } from "../hooks/use-layout-box.js";
+import type { MeasureResult } from "../types.js";
+/**
+ * Width and height in logical Canvas units.
+ *
+ * @see {@link LayoutBox}
+ * @see {@link MeasureResult}
+ */
+export interface Size {
+    /** Horizontal extent in the units of the containing geometry or surface. See {@link Size}. */
+    width: number;
+    /** Vertical extent in the units of the containing geometry or surface. See {@link Size}. */
+    height: number;
+}
+/**
+ * Available and limiting dimensions supplied to layout and measurement.
+ *
+ * @see {@link measureElement}
+ * @see {@link resolveBox}
+ * @see {@link LayoutDiagnosticContext}
+ */
+export interface Constraints {
+    /** Minimum permitted width. See {@link Constraints}. */
+    minWidth: number;
+    /** Maximum permitted width. See {@link Constraints}. */
+    maxWidth: number;
+    /** Minimum permitted height. See {@link Constraints}. */
+    minHeight: number;
+    /** Maximum permitted height. See {@link Constraints}. */
+    maxHeight: number;
+}
+/**
+ * An axis-aligned rectangle in the layout coordinate system.
+ *
+ * @see {@link Size}
+ * @see {@link PibblRenderLayerTarget}
+ * @see {@link ResolvedBoxStyle}
+ * @see {@link useLayoutBox}
+ */
+export interface LayoutBox extends Size {
+    /**
+     * Horizontal coordinate or displacement in the containing coordinate system. See
+     * {@link LayoutBox}.
+     */
+    x: number;
+    /**
+     * Vertical coordinate or displacement in the containing coordinate system. See {@link LayoutBox}
+     * .
+     */
+    y: number;
+}
+/** @internal Temporary render-time allocation and containing-block basis. */
+export interface LayoutContext {
+    allocation: Readonly<LayoutBox>;
+    percentageBasis: Readonly<LayoutBox>;
+}
+/**
+ * Resolved numeric insets for the four sides of a box.
+ *
+ * @see {@link normalizeEdges}
+ * @see {@link BoxStyle}
+ */
+export interface Edges {
+    /** Top edge value or top envelope guide. See {@link Edges}. */
+    top: number;
+    /** Right edge coordinate or inset. See {@link Edges}. */
+    right: number;
+    /** Bottom edge value or bottom envelope guide. See {@link Edges}. */
+    bottom: number;
+    /** Left edge coordinate or inset. See {@link Edges}. */
+    left: number;
+}

package/dist/lib/manipulation/controller-types.d.ts

@@ -0,0 +1,299 @@
+import type { useManipulation } from "./controller.js";
+import type { PibblDragHandleProps } from "./handles.js";
+import type { PibblManipulableProps } from "./manipulable.js";
+import type { ManipulationFrame } from "./frame.js";
+import type { PibblNode } from "../element/types.js";
+import type { Signal, SignalValue, WritableSignal } from "../signals/types.js";
+import type { PibblManipulationBox, PibblManipulationMoveOptions, PibblManipulationResizeOptions, PibblManipulationRotateOptions, PibblResizePosition } from "./types.js";
+/**
+ * The box and rotation that a manipulation controller reads and updates.
+ *
+ * @see {@link PibblManipulationBox}
+ * @see {@link PibblManipulationSnapshot}
+ * @see {@link PibblManipulationEvent}
+ */
+export interface PibblManipulationGeometry {
+    /**
+     * Logical rectangle read and updated by the manipulation controller. See
+     * {@link PibblManipulationBox}.
+     */
+    readonly box: PibblManipulationBox;
+    /** Rotation applied to the containing geometry. See {@link PibblManipulationGeometry}. */
+    readonly rotation: number;
+}
+/**
+ * The move, resize, or rotate operation performed by a manipulation session.
+ *
+ * @see {@link PibblManipulationSnapshot}
+ * @see {@link PibblManipulationActive}
+ */
+export type PibblManipulationOperation = "move" | "resize" | "rotate";
+/**
+ * Why an active manipulation session was cancelled.
+ *
+ * @see {@link PibblManipulationCancelEvent}
+ */
+export type PibblManipulationCancelReason = "explicit" | "escape" | "pointer-cancel" | "capture-lost" | "disabled" | "external-change" | "coordinate-space-changed" | "constraints-unsatisfiable";
+/**
+ * Details identifying an operation currently in progress.
+ *
+ * @see {@link PibblManipulationOperation}
+ * @see {@link PibblResizePosition}
+ * @see {@link PibblManipulationController}
+ */
+export interface PibblManipulationActive {
+    /** Kind of manipulation currently being performed. See {@link PibblManipulationOperation}. */
+    readonly operation: PibblManipulationOperation;
+    /** Handle identity associated with the operation or body. See {@link PibblResizePosition}. */
+    readonly handle: PibblResizePosition | null;
+    /** Browser identifier of the active pointer. See {@link PibblManipulationActive}. */
+    readonly pointerId: number;
+}
+/**
+ * The controller's current geometry and active-operation state.
+ *
+ * @see {@link PibblManipulationOperation}
+ * @see {@link PibblResizePosition}
+ * @see {@link PibblManipulationGeometry}
+ * @see {@link PibblManipulationController}
+ * @see {@link PibblManipulationEvent}
+ */
+export interface PibblManipulationSnapshot {
+    /** Kind of manipulation currently being performed. See {@link PibblManipulationOperation}. */
+    readonly operation: PibblManipulationOperation;
+    /** Handle identity associated with the operation or body. See {@link PibblResizePosition}. */
+    readonly handle: PibblResizePosition | null;
+    /** Geometry captured when this manipulation began. See {@link PibblManipulationGeometry}. */
+    readonly initial: PibblManipulationGeometry;
+    /**
+     * Geometry proposed before constraints and snapping are applied. See
+     * {@link PibblManipulationGeometry}.
+     */
+    readonly proposed: PibblManipulationGeometry;
+    /** Geometry after constraints and snapping are applied. See {@link PibblManipulationGeometry}. */
+    readonly applied: PibblManipulationGeometry;
+    /**
+     * Whether snapping is currently enabled for this operation. See {@link PibblManipulationSnapshot}
+     * .
+     */
+    readonly snapActive: boolean;
+    /**
+     * Whether the applied geometry satisfies the active snap constraint. See
+     * {@link PibblManipulationSnapshot}.
+     */
+    readonly snapSatisfied: boolean;
+}
+/**
+ * Geometry and operation information emitted while manipulating a target.
+ *
+ * @see {@link PibblManipulationSnapshot}
+ * @see {@link PibblManipulationGeometry}
+ * @see {@link PibblManipulationOptions}
+ * @see {@link PibblManipulationCommitEvent}
+ */
+export interface PibblManipulationEvent extends PibblManipulationSnapshot {
+    /** Geometry before this manipulation update. See {@link PibblManipulationGeometry}. */
+    readonly before: PibblManipulationGeometry;
+    /** Geometry after this manipulation update. See {@link PibblManipulationGeometry}. */
+    readonly after: PibblManipulationGeometry;
+}
+/**
+ * The final geometry of a successfully committed manipulation.
+ *
+ * @see {@link PibblManipulationEvent}
+ * @see {@link PibblManipulationOptions}
+ */
+export interface PibblManipulationCommitEvent extends PibblManipulationEvent {
+    /**
+     * Whether the committed geometry differs from the starting geometry. See
+     * {@link PibblManipulationCommitEvent}.
+     */
+    readonly changed: boolean;
+}
+/**
+ * Cancellation reason and geometry information for an abandoned manipulation.
+ *
+ * @see {@link PibblManipulationEvent}
+ * @see {@link PibblManipulationCancelReason}
+ * @see {@link PibblManipulationOptions}
+ */
+export interface PibblManipulationCancelEvent extends PibblManipulationEvent {
+    /**
+     * Reason the operation could not produce its ordinary result. See
+     * {@link PibblManipulationCancelReason}.
+     */
+    readonly reason: PibblManipulationCancelReason;
+}
+/**
+ * Translation constraints and signal-capable enablement and snapping configuration.
+ *
+ * @see {@link SignalValue}
+ * @see {@link PibblManipulationOptions}
+ * @see {@link PibblManipulableProps}
+ */
+export type PibblManipulationMoveInput = Omit<PibblManipulationMoveOptions, "snap"> & {
+    /** Whether this operation or resource participates in updates. See {@link SignalValue}. */
+    readonly enabled?: SignalValue<boolean>;
+    /**
+     * Snapping configuration for the manipulation operation. See {@link PibblManipulationMoveOptions}
+     * , {@link SignalValue}.
+     */
+    readonly snap?: Omit<NonNullable<PibblManipulationMoveOptions["snap"]>, "enabled"> & {
+        /** Whether this operation or resource participates in updates. See {@link SignalValue}. */
+        readonly enabled?: SignalValue<boolean>;
+    };
+};
+type SignalEnabled<T> = T extends unknown ? Omit<T, "enabled"> & {
+    readonly enabled?: SignalValue<boolean>;
+} : never;
+/**
+ * Resize constraints and signal-capable enablement and snapping configuration.
+ *
+ * @see {@link SignalValue}
+ * @see {@link PibblManipulationOptions}
+ * @see {@link PibblManipulableProps}
+ */
+export type PibblManipulationResizeInput = Omit<PibblManipulationResizeOptions, "snap"> & {
+    /** Whether this operation or resource participates in updates. See {@link SignalValue}. */
+    readonly enabled?: SignalValue<boolean>;
+    /**
+     * Snapping configuration for the manipulation operation. See {@link SignalEnabled},
+     * {@link PibblManipulationResizeOptions}.
+     */
+    readonly snap?: SignalEnabled<NonNullable<PibblManipulationResizeOptions["snap"]>>;
+};
+/**
+ * Rotation constraints and signal-capable enablement and snapping configuration.
+ *
+ * @see {@link SignalValue}
+ * @see {@link PibblManipulationOptions}
+ * @see {@link PibblManipulableProps}
+ */
+export type PibblManipulationRotateInput = Omit<PibblManipulationRotateOptions, "snap"> & {
+    /** Whether this operation or resource participates in updates. See {@link SignalValue}. */
+    readonly enabled?: SignalValue<boolean>;
+    /**
+     * Snapping configuration for the manipulation operation. See {@link SignalEnabled},
+     * {@link PibblManipulationRotateOptions}.
+     */
+    readonly snap?: SignalEnabled<NonNullable<PibblManipulationRotateOptions["snap"]>>;
+};
+/**
+ * Geometry, constraints, and lifecycle callbacks for a manipulation controller.
+ *
+ * @see {@link WritableSignal}
+ * @see {@link PibblManipulationBox}
+ * @see {@link PibblManipulationMoveInput}
+ * @see {@link PibblManipulationResizeInput}
+ * @see {@link PibblManipulationRotateInput}
+ * @see {@link PibblManipulationEvent}
+ * @see {@link PibblManipulationCommitEvent}
+ * @see {@link PibblManipulationCancelEvent}
+ * @see {@link useManipulation}
+ * @see {@link PibblManipulableProps}
+ */
+export interface PibblManipulationOptions {
+    /**
+     * Logical rectangle read and updated by the manipulation controller. See {@link WritableSignal}
+     * , {@link PibblManipulationBox}.
+     */
+    readonly box: WritableSignal<PibblManipulationBox>;
+    /** Rotation applied to the containing geometry. See {@link WritableSignal}. */
+    readonly rotation?: WritableSignal<number>;
+    /**
+     * Configuration for translation of the manipulation target. See {@link PibblManipulationMoveInput}
+     * .
+     */
+    readonly move?: PibblManipulationMoveInput;
+    /**
+     * Configuration or operation for changing the target dimensions. See
+     * {@link PibblManipulationResizeInput}.
+     */
+    readonly resize?: PibblManipulationResizeInput;
+    /**
+     * Configuration for rotation of the manipulation target. See {@link PibblManipulationRotateInput}
+     * .
+     */
+    readonly rotate?: PibblManipulationRotateInput;
+    /**
+     * Receives the initial state when a manipulation begins. See {@link PibblManipulationEvent}.
+     * @param event - Current manipulation session and proposed geometry. See
+     * {@link PibblManipulationEvent} .
+     */
+    readonly onStart?: (event: PibblManipulationEvent) => void;
+    /**
+     * Receives geometry changes during an active manipulation. See {@link PibblManipulationEvent}.
+     * @param event - Current manipulation session and proposed geometry. See
+     * {@link PibblManipulationEvent} .
+     */
+    readonly onChange?: (event: PibblManipulationEvent) => void;
+    /**
+     * Receives the final state of a committed manipulation. See {@link PibblManipulationCommitEvent}.
+     * @param event - Successfully committed manipulation state. See
+     * {@link PibblManipulationCommitEvent} .
+     */
+    readonly onCommit?: (event: PibblManipulationCommitEvent) => void;
+    /**
+     * Receives the reason and state of a cancelled manipulation. See
+     * {@link PibblManipulationCancelEvent}.
+     * @param event - Canceled manipulation state and cancellation reason. See
+     * {@link PibblManipulationCancelEvent} .
+     */
+    readonly onCancel?: (event: PibblManipulationCancelEvent) => void;
+}
+/**
+ * Authored inputs for ManipulationFrame, including the declared data and presentation options.
+ *
+ * @see {@link PibblManipulationController}
+ * @see {@link WritableSignal}
+ * @see {@link PibblManipulationBox}
+ * @see {@link PibblNode}
+ * @see {@link ManipulationFrame}
+ */
+export interface PibblManipulationFrameProps {
+    /**
+     * Controller owning the current interaction or mounted scenario. See
+     * {@link PibblManipulationController}.
+     */
+    readonly controller: PibblManipulationController;
+    /**
+     * Declared presentation and layout properties. See {@link WritableSignal},
+     * {@link PibblManipulationBox}.
+     */
+    readonly style: WritableSignal<PibblManipulationBox>;
+    /** Descendant content or the callback that supplies it. See {@link PibblNode}. */
+    readonly children?: PibblNode;
+}
+/**
+ * Stable controls and reactive geometry for one mounted manipulation session.
+ *
+ * @see {@link Signal}
+ * @see {@link PibblManipulationActive}
+ * @see {@link PibblManipulationSnapshot}
+ * @see {@link PibblManipulationFrameProps}
+ * @see {@link useManipulation}
+ * @see {@link PibblDragHandleProps}
+ */
+export interface PibblManipulationController {
+    /**
+     * Current active operation or its presentation configuration. See {@link Signal},
+     * {@link PibblManipulationActive}.
+     */
+    readonly active: Signal<PibblManipulationActive | null>;
+    /**
+     * Current immutable observation of the manipulation session. See {@link Signal},
+     * {@link PibblManipulationSnapshot}.
+     */
+    readonly snapshot: Signal<PibblManipulationSnapshot | null>;
+    /**
+     * Props for presenting the controller's current manipulation frame. See
+     * {@link PibblManipulationFrameProps}.
+     */
+    readonly frameProps: PibblManipulationFrameProps;
+    /**
+     * Cancels the active manipulation and applies its cancellation policy. See
+     * {@link PibblManipulationController}.
+     */
+    cancel(): void;
+}
+export {};

package/dist/lib/manipulation/controller.d.ts

@@ -0,0 +1,57 @@
+import type { PibblEventHandlers, PibblEventTarget, PibblPointerEvent } from "../events/types.js";
+import type { PibblComponentRefs, PibblInstance } from "../types.js";
+import type { WritableSignal } from "../signals/types.js";
+import type { PibblResizePosition } from "./types.js";
+import type { PibblManipulationActive, PibblManipulationController, PibblManipulationGeometry, PibblManipulationOperation, PibblManipulationOptions, PibblManipulationSnapshot } from "./controller-types.js";
+type PointerSample = Pick<PibblPointerEvent, "pointerId" | "x" | "y" | "clientX" | "clientY" | "shiftKey" | "altKey" | "ctrlKey" | "metaKey">;
+interface Session {
+    operation: PibblManipulationOperation;
+    handle?: PibblResizePosition;
+    pointerId: number;
+    target: PibblEventTarget;
+    before: PibblManipulationGeometry;
+    last: PibblManipulationGeometry;
+    point: DOMPoint;
+    clientX: number;
+    clientY: number;
+    parent: DOMMatrix;
+    started: boolean;
+    angle: number;
+    rotationDelta: number;
+    snapshot: PibblManipulationSnapshot;
+    coordinateMapping: readonly number[];
+    source?: object;
+    releaseObservation?: () => void;
+    sample?: PointerSample;
+}
+export interface ManipulationState {
+    controller: PibblManipulationController;
+    options: PibblManipulationOptions;
+    alive: boolean;
+    root: PibblInstance;
+    frame?: PibblComponentRefs<any>;
+    parent: DOMMatrix;
+    coordinateMapping?: readonly number[];
+    session?: Session;
+    active: WritableSignal<PibblManipulationActive | null>;
+    snapshot: WritableSignal<PibblManipulationSnapshot | null>;
+}
+export declare function manipulationState(controller: PibblManipulationController): ManipulationState;
+/** Release capture synchronously; rollback can defer under renderer write guards. */
+export declare function detachManipulationFrame(state: ManipulationState): void;
+/**
+ * Creates a mount-owned controller for moving, resizing, and rotating declared geometry.
+ *
+ * @param options - Target state, enabled operations, constraints, and lifecycle callbacks. See
+ * {@link PibblManipulationOptions} .
+ * @returns Stable controls and state for the mounted manipulation interaction. See
+ * {@link PibblManipulationController} .
+ *
+ * @see {@link PibblManipulationOptions}
+ * @see {@link PibblManipulationController}
+ */
+export declare function useManipulation(options: PibblManipulationOptions): PibblManipulationController;
+/** @internal Identifies one private handle source for readout presentation. */
+export declare function isManipulationSourceActive(controller: PibblManipulationController, source: object): boolean;
+export declare function manipulationHandlers(controller: PibblManipulationController, operation: PibblManipulationOperation, handle?: PibblResizePosition, source?: object): PibblEventHandlers;
+export {};