fancy-ui-react 0.2.0

package/dist/components/status-morph/StatusMorph.js

@@ -0,0 +1,110 @@
+"use client";
+import { jsxs, jsx } from "react/jsx-runtime";
+import { forwardRef, useRef, useEffect } from "react";
+import { cn } from "../../utils.js";
+import { Portal } from "../../internals/Portal.js";
+import { vibrate } from "../../internals/motion/haptics.js";
+/* empty css                 */
+const DEFAULT_LABELS = { loading: "Loading", success: "Done", error: "Failed" };
+const StatusMorph = forwardRef(function StatusMorph2({
+  state = "idle",
+  onStateChange,
+  resetAfter = 1800,
+  labels = {},
+  tone = "current",
+  haptic = false,
+  idle,
+  className,
+  ...restProps
+}, ref) {
+  const resolvedLabels = { ...DEFAULT_LABELS, ...labels };
+  const liveText = state === "loading" ? resolvedLabels.loading : state === "success" ? resolvedLabels.success : state === "error" ? resolvedLabels.error : "";
+  const onStateChangeRef = useRef(onStateChange);
+  onStateChangeRef.current = onStateChange;
+  useEffect(() => {
+    if ((state === "success" || state === "error") && resetAfter > 0) {
+      const timer = setTimeout(() => {
+        onStateChangeRef.current?.("idle");
+      }, resetAfter);
+      return () => clearTimeout(timer);
+    }
+  }, [state, resetAfter]);
+  const lastHapticState = useRef(void 0);
+  useEffect(() => {
+    const current = state;
+    const changed = current !== lastHapticState.current;
+    lastHapticState.current = current;
+    if (!haptic || !changed) return;
+    if (current === "success") vibrate("success");
+    else if (current === "error") vibrate("error");
+  }, [state, haptic]);
+  return /* @__PURE__ */ jsxs(
+    "span",
+    {
+      ref,
+      className: cn("ft-statusmorph", className),
+      ...restProps,
+      "data-state": state,
+      "data-tone": tone,
+      children: [
+        idle ? /* @__PURE__ */ jsx("span", { className: "ft-statusmorph-idle", "aria-hidden": "true", children: idle }) : null,
+        /* @__PURE__ */ jsxs("svg", { className: "ft-statusmorph-svg", viewBox: "0 0 24 24", "aria-hidden": "true", "data-state": state, children: [
+          /* @__PURE__ */ jsx(
+            "circle",
+            {
+              className: "ft-statusmorph-track",
+              cx: "12",
+              cy: "12",
+              r: "10",
+              pathLength: "1",
+              vectorEffect: "non-scaling-stroke"
+            }
+          ),
+          /* @__PURE__ */ jsx(
+            "circle",
+            {
+              className: "ft-statusmorph-arc",
+              cx: "12",
+              cy: "12",
+              r: "10",
+              pathLength: "1",
+              vectorEffect: "non-scaling-stroke"
+            }
+          ),
+          /* @__PURE__ */ jsx(
+            "path",
+            {
+              className: "ft-statusmorph-check",
+              d: "M7 12.5l3.5 3.5L17 9",
+              pathLength: "1",
+              vectorEffect: "non-scaling-stroke"
+            }
+          ),
+          /* @__PURE__ */ jsx(
+            "path",
+            {
+              className: "ft-statusmorph-cross-a",
+              d: "M8 8l8 8",
+              pathLength: "1",
+              vectorEffect: "non-scaling-stroke"
+            }
+          ),
+          /* @__PURE__ */ jsx(
+            "path",
+            {
+              className: "ft-statusmorph-cross-b",
+              d: "M16 8l-8 8",
+              pathLength: "1",
+              vectorEffect: "non-scaling-stroke"
+            }
+          )
+        ] }),
+        /* @__PURE__ */ jsx(Portal, { children: /* @__PURE__ */ jsx("div", { role: "status", "aria-live": state === "error" ? "assertive" : "polite", className: "sr-only", children: liveText }) })
+      ]
+    }
+  );
+});
+StatusMorph.displayName = "StatusMorph";
+export {
+  StatusMorph
+};

package/dist/components/status-morph/index.d.ts

@@ -0,0 +1,2 @@
+export { StatusMorph } from "./StatusMorph.js";
+export type { StatusMorphProps, StatusMorphState } from "./StatusMorph.js";

package/dist/components/stepper/Step.d.ts

@@ -0,0 +1,24 @@
+import type { ReactNode } from "react";
+export interface StepProps {
+    /**
+     * The step's primary label. Required: with `children` also omitted, a
+     * clickable step's only accessible text is its `sr-only` status span —
+     * every upcoming step in the same `Stepper` would then read as the
+     * identical "not started, button" with nothing to tell them apart.
+     */
+    label: string;
+    /** Optional secondary line shown under the label. */
+    description?: string;
+    /** Overrides the bullet's default content (checkmark / number / outline). */
+    children?: ReactNode;
+    /** Additional CSS classes */
+    className?: string;
+}
+/**
+ * One stop on a `Stepper`'s rail. Its number and status come from its
+ * position among its registered siblings, never from a prop.
+ *
+ * The root element arrives through the ref channel rather than a `ref`
+ * prop, per PORTING.md — the Svelte source declares `ref = $bindable(null)`.
+ */
+export declare const Step: import("react").ForwardRefExoticComponent<StepProps & import("react").RefAttributes<HTMLLIElement>>;

package/dist/components/stepper/Step.js

@@ -0,0 +1,152 @@
+"use client";
+import { jsxs, jsx, Fragment } from "react/jsx-runtime";
+import { forwardRef, useContext } from "react";
+import { cn } from "../../utils.js";
+import { useFancyId } from "../../internals/use-id.js";
+import { useIsomorphicLayoutEffect } from "../../internals/dom/ssr.js";
+import { STEPPER_KEY } from "./types.js";
+/* empty css         */
+const STATUS_TEXT = {
+  done: "completed",
+  current: "current step",
+  upcoming: "not started"
+};
+const Step = forwardRef(function Step2({ label, description, children, className }, ref) {
+  const stepper = useContext(STEPPER_KEY);
+  const id = useFancyId();
+  const register = stepper?.register;
+  useIsomorphicLayoutEffect(() => {
+    if (!register) return;
+    return register(id);
+  }, [register, id]);
+  const index = stepper ? stepper.indexOf(id) : -1;
+  const status = (() => {
+    if (!stepper || index === -1) return "upcoming";
+    if (index < stepper.current) return "done";
+    if (index === stepper.current) return "current";
+    return "upcoming";
+  })();
+  const orientation = stepper?.orientation ?? "horizontal";
+  const clickable = stepper?.clickable ?? false;
+  const isFirst = index === 0;
+  const isLast = stepper ? index === stepper.count - 1 : true;
+  const connectorDone = stepper ? index <= stepper.current : false;
+  function handleClick() {
+    if (!stepper || !clickable || index === -1) return;
+    stepper.select(index);
+  }
+  const bulletClasses = cn(
+    "ft-step-bullet relative inline-flex size-7 shrink-0 items-center justify-center rounded-full text-[13px] font-semibold",
+    status === "done" && "ft-step-bullet-done",
+    status === "current" && "ft-step-bullet-current",
+    status === "upcoming" && "border-border text-muted-foreground border-[1.5px] bg-transparent"
+  );
+  const defaultBullet = status === "done" ? /* @__PURE__ */ jsx(
+    "svg",
+    {
+      className: "size-3.5",
+      viewBox: "0 0 24 24",
+      fill: "none",
+      stroke: "currentColor",
+      strokeWidth: "2.5",
+      strokeLinecap: "round",
+      strokeLinejoin: "round",
+      "aria-hidden": "true",
+      children: /* @__PURE__ */ jsx("path", { d: "M20 6 9 17l-5-5" })
+    }
+  ) : /* @__PURE__ */ jsx("span", { "aria-hidden": "true", children: index + 1 });
+  const bulletContent = /* @__PURE__ */ jsxs("span", { className: bulletClasses, "data-status": status, children: [
+    children ?? defaultBullet,
+    /* @__PURE__ */ jsxs("span", { className: "sr-only", children: [
+      " ",
+      STATUS_TEXT[status]
+    ] })
+  ] });
+  const textContent = /* @__PURE__ */ jsxs(
+    "span",
+    {
+      className: cn("flex flex-col", orientation === "horizontal" && "items-center text-center"),
+      children: [
+        label ? /* @__PURE__ */ jsx(
+          "span",
+          {
+            className: cn(
+              "text-xs",
+              status === "current" ? "text-foreground font-medium" : "text-muted-foreground"
+            ),
+            children: label
+          }
+        ) : null,
+        description ? /* @__PURE__ */ jsx("span", { className: "text-muted-foreground text-xs", children: description }) : null
+      ]
+    }
+  );
+  return /* @__PURE__ */ jsx(
+    "li",
+    {
+      ref,
+      className: cn(
+        "ft-step flex",
+        orientation === "vertical" ? cn("flex-row items-stretch gap-3", isLast ? "pb-0" : "pb-6") : cn("flex-col items-center", isFirst ? "flex-none" : "flex-1"),
+        className
+      ),
+      "data-status": status,
+      "data-orientation": orientation,
+      "aria-current": status === "current" ? "step" : void 0,
+      children: orientation === "horizontal" ? /* @__PURE__ */ jsxs("div", { className: "flex w-full items-center", children: [
+        !isFirst && /* @__PURE__ */ jsx(
+          "span",
+          {
+            className: cn(
+              "ft-step-connector mt-[13px] h-0.5 flex-1",
+              connectorDone ? "ft-step-connector-done" : "bg-border"
+            ),
+            "aria-hidden": "true"
+          }
+        ),
+        clickable ? /* @__PURE__ */ jsxs(
+          "button",
+          {
+            type: "button",
+            className: "ft-step-trigger flex shrink-0 cursor-pointer flex-col items-center gap-1.5 px-1 focus-visible:outline-none",
+            onClick: handleClick,
+            children: [
+              bulletContent,
+              textContent
+            ]
+          }
+        ) : /* @__PURE__ */ jsxs("div", { className: "ft-step-trigger flex shrink-0 flex-col items-center gap-1.5 px-1", children: [
+          bulletContent,
+          textContent
+        ] })
+      ] }) : /* @__PURE__ */ jsxs(Fragment, { children: [
+        /* @__PURE__ */ jsxs("div", { className: "flex flex-col items-center self-stretch", children: [
+          bulletContent,
+          !isLast && /* @__PURE__ */ jsx(
+            "span",
+            {
+              className: cn(
+                "ft-step-connector my-1 w-0.5 flex-1",
+                connectorDone ? "ft-step-connector-done" : "bg-border"
+              ),
+              "aria-hidden": "true"
+            }
+          )
+        ] }),
+        clickable ? /* @__PURE__ */ jsx(
+          "button",
+          {
+            type: "button",
+            className: "ft-step-trigger flex cursor-pointer flex-col gap-0.5 pt-0.5 text-left focus-visible:outline-none",
+            onClick: handleClick,
+            children: textContent
+          }
+        ) : /* @__PURE__ */ jsx("div", { className: "ft-step-trigger flex flex-col gap-0.5 pt-0.5 text-left", children: textContent })
+      ] })
+    }
+  );
+});
+Step.displayName = "Step";
+export {
+  Step
+};

package/dist/components/stepper/Stepper.d.ts

@@ -0,0 +1,38 @@
+import type { ReactNode } from "react";
+export interface StepperProps {
+    /**
+     * The active step's 0-based index. Controlled when supplied: pair it
+     * with `onCurrentChange`, the React counterpart of the Svelte source's
+     * `bind:current`. Left out, the stepper keeps the index itself and
+     * starts at 0.
+     */
+    current?: number;
+    /** Called with the new index whenever it changes, however the change happened. */
+    onCurrentChange?: (current: number) => void;
+    /** The rail's stacking axis. Defaults to `"horizontal"`. */
+    orientation?: "horizontal" | "vertical";
+    /** Whether steps render as buttons a reader can click to jump between them. Defaults to `false`. */
+    clickable?: boolean;
+    /** Called with a step's index when it's activated by a click. Only fires when `clickable`. */
+    onStepClick?: (index: number) => void;
+    /** The `Step`s. */
+    children?: ReactNode;
+    /** Additional CSS classes */
+    className?: string;
+    /**
+     * Plays the select cue through the sound controller. Off by default;
+     * only audible once the user has enabled sound.
+     */
+    sound?: boolean;
+}
+/**
+ * The rail a set of `Step`s reads its shared state from.
+ *
+ * The root element arrives through the ref channel rather than a `ref`
+ * prop, per PORTING.md — the Svelte source declares `ref = $bindable(null)`.
+ *
+ * Rest props are not spread: the Svelte source reads only these props off
+ * `$props()` and has no `...restProps`, so the port carries no wider
+ * attribute surface than the component it mirrors.
+ */
+export declare const Stepper: import("react").ForwardRefExoticComponent<StepperProps & import("react").RefAttributes<HTMLOListElement>>;

package/dist/components/stepper/Stepper.js

@@ -0,0 +1,79 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import { forwardRef, useState, useRef, useCallback, useMemo } from "react";
+import { cn } from "../../utils.js";
+import { useSoundCue } from "../../sound/use-sound.js";
+import { STEPPER_KEY } from "./types.js";
+const Stepper = forwardRef(function Stepper2({
+  current,
+  onCurrentChange,
+  orientation = "horizontal",
+  clickable = false,
+  onStepClick,
+  children,
+  className,
+  sound = false
+}, ref) {
+  const [uncontrolledCurrent, setUncontrolledCurrent] = useState(0);
+  const isControlled = current !== void 0;
+  const activeIndex = isControlled ? current : uncontrolledCurrent;
+  const registryRef = useRef([]);
+  const [registered, setRegistered] = useState([]);
+  const register = useCallback((id) => {
+    if (!registryRef.current.includes(id)) {
+      registryRef.current = [...registryRef.current, id];
+      setRegistered(registryRef.current);
+    }
+    return () => {
+      const index = registryRef.current.indexOf(id);
+      if (index !== -1) {
+        const next = [...registryRef.current];
+        next.splice(index, 1);
+        registryRef.current = next;
+        setRegistered(next);
+      }
+    };
+  }, []);
+  const indexOf = useCallback((id) => registered.indexOf(id), [registered]);
+  const playCue = useSoundCue(sound);
+  const select = useCallback(
+    (index) => {
+      if (!clickable) return;
+      if (activeIndex !== index) playCue("select");
+      onStepClick?.(index);
+      if (!isControlled) setUncontrolledCurrent(index);
+      onCurrentChange?.(index);
+    },
+    [clickable, isControlled, onStepClick, onCurrentChange, activeIndex, playCue]
+  );
+  const context = useMemo(
+    () => ({
+      orientation,
+      clickable,
+      current: activeIndex,
+      count: registered.length,
+      register,
+      indexOf,
+      select
+    }),
+    [orientation, clickable, activeIndex, registered, register, indexOf, select]
+  );
+  return /* @__PURE__ */ jsx(STEPPER_KEY.Provider, { value: context, children: /* @__PURE__ */ jsx(
+    "ol",
+    {
+      ref,
+      role: "list",
+      className: cn(
+        "ft-stepper flex list-none",
+        orientation === "vertical" ? "flex-col" : "w-full items-start",
+        className
+      ),
+      "data-orientation": orientation,
+      children
+    }
+  ) });
+});
+Stepper.displayName = "Stepper";
+export {
+  Stepper
+};

package/dist/components/stepper/index.d.ts

@@ -0,0 +1,6 @@
+export { Stepper } from "./Stepper.js";
+export type { StepperProps } from "./Stepper.js";
+export { Step } from "./Step.js";
+export type { StepProps } from "./Step.js";
+export { STEPPER_KEY } from "./types.js";
+export type { StepperContext } from "./types.js";

package/dist/components/stepper/types.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The contract between the stepper root and its steps.
+ *
+ * `Stepper` owns the active index; every `Step` reads it through
+ * context instead of a prop threaded down by hand, the same
+ * "root owns the shared state, items read it" shape a toggle group and
+ * its items use for roving focus.
+ *
+ * A step's own number and status (done/current/upcoming) are derived from
+ * its position among its registered siblings, not from any prop the
+ * consumer supplies. Registration order is trusted as step order here —
+ * unlike the live-DOM-position re-query `menu.ts` does for arrow-key
+ * navigation, steps are a static composition (typically one `map` over a
+ * fixed list) that doesn't reorder after mount, so the order each `Step`
+ * registers in in its own mount effect already *is* DOM order. React runs
+ * child effects before parent effects and in mount order, so siblings
+ * register top-to-bottom exactly as they do on the Svelte side.
+ *
+ * That assumption has a consequence, not just a precondition: reordering
+ * already-mounted `Step`s (a keyed list that moves an existing item rather
+ * than adding or removing one) does not re-run that item's registration
+ * effect, so `indexOf` keeps returning its *original* mount position —
+ * reordering without add or remove leaves every step's number, status,
+ * checkmark and `aria-current` pinned to its original mount position.
+ * Adding or removing a step settles correctly, since that's a genuine
+ * mount/unmount. Only pure reordering is affected.
+ */
+export interface StepperContext {
+    /** The rail's stacking axis. */
+    readonly orientation: "horizontal" | "vertical";
+    /** Whether steps render as buttons a reader can click to jump. */
+    readonly clickable: boolean;
+    /** The active step's 0-based index. */
+    readonly current: number;
+    /** Total number of currently registered steps. */
+    readonly count: number;
+    /**
+     * Registers a step under a stable per-instance id (typically
+     * `useFancyId()`). Returns an unregister function; call it on unmount.
+     *
+     * Identity-stable for the life of the root, on purpose: a `Step`'s
+     * registration effect depends on this function, and a function rebuilt
+     * on every context change would re-run that effect — unregister,
+     * register, re-render, unregister — forever. See `Stepper.tsx`.
+     */
+    register(id: string): () => void;
+    /** `id`'s 0-based position among registered steps, or -1 before it has registered. */
+    indexOf(id: string): number;
+    /** Jumps to `index`, if `clickable`. No-op otherwise. */
+    select(index: number): void;
+}
+/**
+ * The context a `Step` reads to learn its position, its status and the
+ * rail's shape. The Svelte source publishes it under a `Symbol` context
+ * key; React's own context object plays that role here, so the exported
+ * name is kept and the value is a `React.Context` rather than a symbol:
+ *
+ * ```tsx
+ * const stepper = useContext(STEPPER_KEY);
+ * ```
+ *
+ * Read it as optional — a `Step` rendered outside a `Stepper` gets
+ * `undefined` rather than throwing, and renders as a plain, always
+ * "upcoming", never-clickable item.
+ */
+export declare const STEPPER_KEY: import("react").Context<StepperContext | undefined>;

package/dist/components/stepper/types.js

@@ -0,0 +1,7 @@
+"use client";
+import { createContext } from "react";
+const STEPPER_KEY = createContext(void 0);
+STEPPER_KEY.displayName = "StepperContext";
+export {
+  STEPPER_KEY
+};

package/dist/components/sticky-scroll/StickyScroll.d.ts

@@ -0,0 +1,40 @@
+import type { HTMLAttributes, ReactElement, ReactNode, RefAttributes } from "react";
+interface BaseProps<T> {
+    /** The items rendered down the scrolling column, one `item` render per row. */
+    items: T[];
+    /** Renders one row. `(item, index, active)` — `active` is true only for the current `activeIndex`. */
+    item: (item: T, index: number, active: boolean) => ReactNode;
+    /** Renders the sticky panel's content for the active item. `(item, index)`. */
+    panel: (item: T, index: number) => ReactNode;
+    /**
+     * The currently active item's index. Holds its last value when nothing
+     * intersects the centre line. Passing it makes the index controlled — the
+     * React counterpart of the Svelte source's `$bindable`; omit it entirely to
+     * let the component own the index and report every change through `onChange`.
+     */
+    activeIndex?: number;
+    /** Which logical side the sticky panel sits on. Flips physically under `dir="rtl"` — nothing extra to configure. */
+    panelSide?: "start" | "end";
+    /** Whether the panel crossfades between items. Effective value is always `false` under reduced motion. */
+    crossfade?: boolean;
+    /** Additional CSS classes for the sticky panel wrapper. */
+    panelClass?: string;
+    /** Whether the panel is `aria-hidden` — the default, since it normally mirrors an already-visible active item. Set `false` when the panel holds content found nowhere else. */
+    panelHidden?: boolean;
+    /** Called when the active index changes — never on every scroll tick, only on an actual change. */
+    onChange?: (index: number, item: T) => void;
+    /** Additional CSS classes */
+    className?: string;
+}
+/**
+ * Props for StickyScroll
+ */
+export interface StickyScrollProps<T> extends Omit<HTMLAttributes<HTMLDivElement>, keyof BaseProps<unknown> | "children">, BaseProps<T> {
+}
+/** Keeps the source's generic surface: a consumer imports the props as
+ *  `StickyScrollProps<MyItem>`, and the component infers `T` from whatever
+ *  `items` it's actually given. `forwardRef` erases a render function's type
+ *  parameter, so the generic call signature is restored by assertion. */
+type StickyScrollComponent = <T>(props: StickyScrollProps<T> & RefAttributes<HTMLDivElement>) => ReactElement;
+export declare const StickyScroll: StickyScrollComponent;
+export {};