clip-pal 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,364 @@
+import * as react from 'react';
+import { CSSProperties, ReactNode } from 'react';
+
+declare const PAL_GESTURES: {
+    readonly lean: 4000;
+    readonly look: 3200;
+    readonly knock: 3400;
+    readonly kick: 4200;
+    readonly crack: 3000;
+    readonly dance: 3000;
+    readonly wave: 2400;
+    readonly hop: 2200;
+    readonly spin: 1400;
+    readonly nod: 1600;
+    readonly shake: 1600;
+    readonly bow: 2200;
+    readonly backflip: 1600;
+    readonly shiver: 1400;
+    readonly doze: 3200;
+};
+declare const PAL_POSES: readonly ["unbend", "curl", "heart", "question", "exclaim", "key"];
+declare const PAL_POSE_IN_MS = 900;
+declare const PAL_POSE_OUT_MS = 700;
+type PalGesture = keyof typeof PAL_GESTURES;
+type PalPose = (typeof PAL_POSES)[number];
+type PalEmote = PalGesture | PalPose;
+declare const PAL_EMOTES: readonly PalEmote[];
+declare function isPose(emote: PalEmote): emote is PalPose;
+type PalLine = readonly [text: string, emote: PalEmote];
+type PalStop = {
+    id: string;
+    anchor: string;
+    /** beside the anchor, or parked in one of the gutters either side of the content column */
+    place: "beside" | "gutter-left" | "gutter-right";
+    /** horizontal clearance from the anchor when `place` is "beside" (default 26) */
+    gap?: number;
+    lines: readonly PalLine[];
+};
+type PalEye = {
+    cx: number;
+    cy: number;
+    r: number;
+};
+type PalShape = {
+    body: string;
+    leg: string;
+    hip: readonly [x: number, y: number];
+    eyes: readonly [PalEye, PalEye];
+};
+declare const PAL_SHAPES: {
+    /** the everyday Gem clip — the default */
+    readonly gem: {
+        readonly body: "M15 62 L15 14 C15 7 19 3 25 3 C31 3 35 7 35 14 L35 50 C35 55 32 58 28 58 C24 58 21 55 21 50 L21 20";
+        readonly leg: "M15 63 C15 70 20 73 27 73 C34 73 41 69 41 61 L41 54";
+        readonly hip: readonly [15, 63];
+        readonly eyes: readonly [{
+            readonly cx: 22;
+            readonly cy: 12;
+            readonly r: 2.4;
+        }, {
+            readonly cx: 30;
+            readonly cy: 12;
+            readonly r: 2.4;
+        }];
+    };
+    /** rounder, chubbier loops */
+    readonly round: {
+        readonly body: "M13 60 L13 18 C13 8 18 3 25 3 C32 3 37 8 37 18 L37 48 C37 55 33 59 28 59 C23 59 20 55 20 49 L20 24";
+        readonly leg: "M13 61 C13 70 19 74 27 74 C35 74 42 69 42 61 L42 55";
+        readonly hip: readonly [13, 61];
+        readonly eyes: readonly [{
+            readonly cx: 21;
+            readonly cy: 13;
+            readonly r: 2.7;
+        }, {
+            readonly cx: 29;
+            readonly cy: 13;
+            readonly r: 2.7;
+        }];
+    };
+    /** a boxy office clip with squared corners */
+    readonly square: {
+        readonly body: "M14 62 L14 8 C14 5 15 4 18 4 C28 4 32 4 32 4 L36 4 C36 20 36 40 36 54 C36 58 34 59 30 59 C22 59 20 58 20 54 L20 18";
+        readonly leg: "M14 63 C14 72 18 74 26 74 C34 74 42 72 42 64 L42 56";
+        readonly hip: readonly [14, 63];
+        readonly eyes: readonly [{
+            readonly cx: 21;
+            readonly cy: 12;
+            readonly r: 2.4;
+        }, {
+            readonly cx: 29;
+            readonly cy: 12;
+            readonly r: 2.4;
+        }];
+    };
+    /** stretched tall and thin */
+    readonly long: {
+        readonly body: "M17 64 L17 12 C17 6 20 2 25 2 C30 2 33 6 33 12 L33 52 C33 56 31 59 28 59 C25 59 23 56 23 52 L23 18";
+        readonly leg: "M17 65 C17 71 21 74 27 74 C33 74 39 70 39 63 L39 56";
+        readonly hip: readonly [17, 65];
+        readonly eyes: readonly [{
+            readonly cx: 22.5;
+            readonly cy: 10;
+            readonly r: 2;
+        }, {
+            readonly cx: 27.5;
+            readonly cy: 10;
+            readonly r: 2;
+        }];
+    };
+};
+type PalShapeName = keyof typeof PAL_SHAPES;
+declare function resolveShape(shape?: PalShapeName | PalShape): PalShape;
+/** true when a custom shape keeps the command sequence the morphs need */
+declare function isMorphable(shape: PalShape): boolean;
+type PalColors = {
+    /** the paperclip wire */
+    wire?: string;
+    /** eyes, ball, crack, rings, sleep bubbles */
+    face?: string;
+    /** the ball's dark panel */
+    ink?: string;
+    bubbleBg?: string;
+    bubbleBorder?: string;
+    bubbleText?: string;
+    bubbleDot?: string;
+};
+type PalMotion = {
+    /** multiplies every emote's duration; 1 = as authored, 2 = half speed */
+    tempo?: number;
+    /** one stride while walking, ms (default 360) */
+    stepMs?: number;
+    /** idle sway period, ms (default 5000) */
+    swayMs?: number;
+    /** idle sway amplitude, degrees (default 2.5) */
+    swayDeg?: number;
+    /** blink period, ms (default 5000) */
+    blinkMs?: number;
+    /** the companion's float period, ms (default 6000) */
+    floatMs?: number;
+    /** the companion's float height, px (default 8) */
+    floatPx?: number;
+};
+/** a gesture's duration in ms at the given tempo */
+declare function gestureMs(gesture: PalGesture, tempo?: number): number;
+/** inline style carrying the --pal-* variables for the given colours/motion */
+declare function palVars(colors?: PalColors, motion?: PalMotion): Record<string, string>;
+
+type PalSvgProps = {
+    /** rendered width in px; the height follows the 50:80 viewBox unless given */
+    width?: number;
+    /** rendered height in px — set it to squash or stretch him */
+    height?: number;
+    /** swing the leg as if walking */
+    walking?: boolean;
+    /** the gesture or pose to play */
+    emote?: PalEmote | null;
+    /** play the pose's unfolding half rather than holding it */
+    emoteOut?: boolean;
+    /** a preset name or your own wire (see PalShape) */
+    shape?: PalShapeName | PalShape;
+    /** wire thickness in viewBox units (default 5) */
+    strokeWidth?: number;
+    /** "dots" (default) or "none" for a faceless clip */
+    eyes?: "dots" | "none";
+    /** colours as props — the same --pal-* variables, set inline */
+    colors?: PalColors;
+    /** tempo, stride, sway, blink — the same --pal-* variables, set inline */
+    motion?: PalMotion;
+    className?: string;
+    style?: CSSProperties;
+};
+declare function PalSvg({ width, height, walking, emote, emoteOut, shape, strokeWidth, eyes, colors, motion, className, style, }: PalSvgProps): react.JSX.Element;
+
+type PalCompanionHandle = {
+    /** interrupt and say this, optionally acting it out */
+    say: (text: string, emote?: PalEmote | null) => void;
+    /** play a gesture or fold into a pose without saying anything */
+    emote: (name: PalEmote) => void;
+    /** put the bubble away and unfold any held pose */
+    hush: () => void;
+};
+type PalCompanionProps = {
+    /** what he says — a line and the emote that goes with it */
+    lines: readonly PalLine[];
+    /** rendered width in px (default 90) */
+    width?: number;
+    /** rendered height — set it to squash or stretch him */
+    height?: number;
+    /** how long a bubble stays up, ms (default 10 000) */
+    showMs?: number;
+    /** silence between bubbles, ms (default 20 000) */
+    gapMs?: number;
+    /** beat after he scrolls into view before the first line, ms (default 1 500) */
+    firstMs?: number;
+    /** typing dots before the line lands, ms (default 850) */
+    typingMs?: number;
+    /** beat between the bubble and the trick, ms (default 500) */
+    emoteDelayMs?: number;
+    /** widest the bubble grows (default "15rem") */
+    bubbleMaxWidth?: number | string;
+    /** pick lines at random (default) or in order */
+    random?: boolean;
+    /** show the bubble at all (default true) */
+    speak?: boolean;
+    /** act lines out (default true); or a whitelist of the emotes he may use */
+    emotes?: boolean | readonly PalEmote[];
+    /** react to `data-pal-say` elements under the pointer (default true) */
+    hover?: boolean;
+    /** minimum gap between two hover lines, ms (default 1 200) */
+    hoverCooldownMs?: number;
+    /** the gentle up-and-down float (default true) */
+    float?: boolean;
+    /** the idle sway (default true) */
+    sway?: boolean;
+    /** only talk while at least this much of him is on screen (default 0.4) */
+    visibleThreshold?: number;
+    /** a preset name or your own wire */
+    shape?: PalShapeName | PalShape;
+    /** wire thickness in viewBox units (default 5) */
+    strokeWidth?: number;
+    /** "dots" (default) or "none" */
+    eyes?: "dots" | "none";
+    /** colours as props — the same --pal-* variables, set inline */
+    colors?: PalColors;
+    /** tempo, stride, sway, blink, float — the same --pal-* variables, set inline */
+    motion?: PalMotion;
+    onSpeak?: (text: string, emote: PalEmote | null) => void;
+    className?: string;
+    style?: CSSProperties;
+};
+declare const PalCompanion: react.ForwardRefExoticComponent<PalCompanionProps & react.RefAttributes<PalCompanionHandle>>;
+
+type ScrollPalHandle = {
+    /** interrupt and say this, optionally acting it out */
+    say: (text: string, emote?: PalEmote | null) => void;
+    /** play a gesture or fold into a pose without saying anything */
+    emote: (name: PalEmote) => void;
+    /** put the bubble away and unfold any held pose */
+    hush: () => void;
+    /** the stop he is currently at (or "idle" while wandering) */
+    current: () => string;
+};
+type ScrollPalProps = {
+    /** where he stops, top to bottom */
+    stops: readonly PalStop[];
+    /**
+     * Lines for when the page sits still. After `idleAfterMs` without any
+     * input he wanders to the far side of the screen and says one of these;
+     * omit (or set `idle={false}`) to keep him at his post.
+     */
+    idleLines?: readonly PalLine[];
+    /** wander when the page sits still (default true when idleLines given) */
+    idle?: boolean;
+    /** stillness before he wanders off, ms (default 12 000) */
+    idleAfterMs?: number;
+    /** pause between idle wanders, ms (default 20 000) */
+    idleWanderMs?: number;
+    /** narrowest viewport he appears on, px (default 1600) */
+    minViewport?: number;
+    /**
+     * Width of the content column he must stay clear of. A number in px, a
+     * function returning px, or omitted: then the CSS custom property named by
+     * `contentVar` on <html> is read (in rem or px), falling back to 72rem.
+     */
+    contentWidth?: number | (() => number);
+    /** custom property that holds the content width (default "--content-w") */
+    contentVar?: string;
+    /** his smallest rendered width — narrower gutters hide him (default 46) */
+    minWidth?: number;
+    /** his largest rendered width, px (default 92) */
+    maxWidth?: number;
+    /** clearance between him and the content column, px (default 12) */
+    gap?: number;
+    /** clearance from the screen edge, px (default 8) */
+    edge?: number;
+    /** force a gutter for every stop instead of following `place` */
+    side?: "auto" | "left" | "right";
+    /** shift his resting height, px (positive = lower) */
+    offsetY?: number;
+    /** how close to the top/bottom edge he may stand, px (default 150) */
+    yLimitPad?: number;
+    /** z-index of the fixed wrapper (default 40) */
+    zIndex?: number;
+    /** walking speed, px per second (default 480) */
+    speed?: number;
+    /** vertical catch-up speed, px per second (default 540) */
+    speedY?: number;
+    /** ease rate toward the target — bigger snaps, smaller drifts (default 6.32) */
+    ease?: number;
+    /** how far he leans into a stride, degrees (default 9) */
+    leanMax?: number;
+    /** px/s above which he counts as walking (default 27) */
+    walkThreshold?: number;
+    /** how often the anchors are re-measured, ms (default 330) */
+    retargetMs?: number;
+    /** typing dots before the line lands, ms (default 850) */
+    typingMs?: number;
+    /** beat between the bubble and the trick, ms (default 500) */
+    emoteDelayMs?: number;
+    /** widest the bubble grows, px (default 260) */
+    bubbleMaxWidth?: number;
+    /** narrowest the bubble is allowed, px (default 150) */
+    bubbleMinWidth?: number;
+    /** pick lines at random (default) or in order */
+    random?: boolean;
+    /** show the bubble at all (default true) — false makes him mime */
+    speak?: boolean;
+    /** act lines out (default true); or a whitelist of the emotes he may use */
+    emotes?: boolean | readonly PalEmote[];
+    /** react to `data-pal-say` elements under the pointer (default true) */
+    hover?: boolean;
+    /** minimum gap between two hover lines, ms (default 1 200) */
+    hoverCooldownMs?: number;
+    /** let visitors pick him up and drop him (default true) */
+    draggable?: boolean;
+    /** a preset name or your own wire */
+    shape?: PalShapeName | PalShape;
+    /** wire thickness in viewBox units (default 5) */
+    strokeWidth?: number;
+    /** "dots" (default) or "none" */
+    eyes?: "dots" | "none";
+    /** colours as props — the same --pal-* variables, set inline */
+    colors?: PalColors;
+    /** tempo, stride, sway, blink — the same --pal-* variables, set inline */
+    motion?: PalMotion;
+    onArrive?: (stopId: string) => void;
+    onLeave?: (stopId: string) => void;
+    onSpeak?: (text: string, emote: PalEmote | null) => void;
+    onIdle?: () => void;
+    className?: string;
+    style?: CSSProperties;
+};
+declare const ScrollPal: react.ForwardRefExoticComponent<ScrollPalProps & react.RefAttributes<ScrollPalHandle>>;
+
+type BubbleProps = {
+    /** which way the bubble grows — the side its tail is on */
+    side: "left" | "right" | "center";
+    hidden: boolean;
+    typing: boolean;
+    line: string;
+    /** measured box size, or undefined to let it size naturally */
+    box?: {
+        w: number;
+        h: number;
+    } | null;
+    contentStyle?: CSSProperties;
+    contentRef?: React.Ref<HTMLDivElement>;
+    /** offset of the tail from the near edge, in px (ignored for "center") */
+    tailInset?: number;
+    children?: ReactNode;
+};
+declare function Bubble({ side, hidden, typing, line, box, contentStyle, contentRef, tailInset, }: BubbleProps): react.JSX.Element;
+
+declare const HOVER_ATTR = "data-pal-say";
+declare const HOVER_EMOTE_ATTR = "data-pal-emote";
+type HoverLine = {
+    text: string;
+    emote: PalEmote | null;
+    el: Element;
+};
+declare function useHoverSay(enabled: boolean, cooldownMs: number, onSay: (line: HoverLine) => void): void;
+
+export { Bubble, type BubbleProps, HOVER_ATTR, HOVER_EMOTE_ATTR, type HoverLine, PAL_EMOTES, PAL_GESTURES, PAL_POSES, PAL_POSE_IN_MS, PAL_POSE_OUT_MS, PAL_SHAPES, type PalColors, PalCompanion, type PalCompanionHandle, type PalCompanionProps, type PalEmote, type PalEye, type PalGesture, type PalLine, type PalMotion, type PalPose, type PalShape, type PalShapeName, type PalStop, PalSvg, type PalSvgProps, ScrollPal, type ScrollPalHandle, type ScrollPalProps, gestureMs, isMorphable, isPose, palVars, resolveShape, useHoverSay };