fancy-ui-react 0.2.0

package/dist/components/context-menu/types.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The one contract this family publishes of its own, and the React context
+ * that carries it.
+ *
+ * `MenuContext`/`MENU_KEY`/`SubContext`/`SUB_KEY` are NOT redefined here —
+ * they are the exact same contract `DropdownMenuContent` and
+ * `DropdownMenuSubContent` already implement, re-exported from
+ * `dropdown-menu/types.ts` so both families' item-level components
+ * (`*Item`, `*Separator`, `*Label`, `*Sub`, `*SubTrigger`, `*SubContent`)
+ * share one implementation instead of two.
+ *
+ * The Svelte source publishes its own key as a `unique symbol`; React's
+ * context object plays that role here, so the exported name is kept and the
+ * value is a `React.Context` rather than a symbol — the same substitution
+ * `dropdown-menu/types.ts` makes for `DROPDOWN_MENU_KEY`.
+ */
+import type { Side, Align } from "../../internals/anchor-position.js";
+import type { MenuCloseOptions } from "../dropdown-menu/types.js";
+export { MENU_KEY, SUB_KEY } from "../dropdown-menu/types.js";
+export type { MenuContext, MenuCloseOptions, SubContext } from "../dropdown-menu/types.js";
+/** The contract between `ContextMenu` and its own `ContextMenuTrigger`/`ContextMenuContent`. */
+export interface ContextMenuRootContext {
+    readonly contentId: string;
+    readonly side: Side;
+    readonly align: Align;
+    readonly offset: number;
+    readonly loop: boolean;
+    readonly open: boolean;
+    /** The pointer coordinates the panel is anchored at — viewport-relative, matching `MouseEvent.clientX/clientY`. */
+    readonly point: {
+        x: number;
+        y: number;
+    };
+    /** The zero-size virtual anchor element `ContextMenuContent` positions itself against. */
+    readonly anchorRef: HTMLElement | null;
+    /** Whether this menu plays sound cues — mirrors `ContextMenuProps.sound`. */
+    readonly sound: boolean;
+    setAnchorRef(el: HTMLElement | null): void;
+    /** Opens (or, if already open, repositions) the menu at `(x, y)`. */
+    openAt(x: number, y: number): void;
+    /** Closes the menu. Returns focus to whatever held it before the menu opened, by default. */
+    close(options?: MenuCloseOptions): void;
+}
+export declare const CONTEXT_MENU_KEY: import("react").Context<ContextMenuRootContext | undefined>;
+/**
+ * Reads the enclosing `ContextMenu`'s context.
+ *
+ * Both consumers below are only ever mounted by this folder's own root, so
+ * there is no standalone-usage fallback to design for — the same assumption
+ * each source sub-component makes. Internal; not exported from `index.ts`.
+ */
+export declare function useContextMenuRoot(): ContextMenuRootContext;

package/dist/components/context-menu/types.js

@@ -0,0 +1,17 @@
+"use client";
+import { createContext, useContext } from "react";
+const CONTEXT_MENU_KEY = createContext(void 0);
+CONTEXT_MENU_KEY.displayName = "ContextMenuRootContext";
+function useContextMenuRoot() {
+  const value = useContext(CONTEXT_MENU_KEY);
+  if (value === void 0) {
+    throw new Error(
+      "ContextMenuRootContext is missing: this component must be rendered inside its provider."
+    );
+  }
+  return value;
+}
+export {
+  CONTEXT_MENU_KEY,
+  useContextMenuRoot
+};

package/dist/components/context-ring/ContextRing.d.ts

@@ -0,0 +1,33 @@
+import type { TokenUsageData } from "../../internals/ai-types.js";
+/**
+ * Props for ContextRing
+ */
+export interface ContextRingProps {
+    /** Context-window consumption: how many tokens are used, out of how many, and of what. */
+    usage: TokenUsageData;
+    /** Outer diameter of the ring, in pixels. */
+    size?: number;
+    /** Thickness of both the track and the arc, in pixels. */
+    strokeWidth?: number;
+    /** Whether the compact "12.4k / 200k" figure is shown beside the ring. */
+    showLabel?: boolean;
+    /** Fraction at which the ring leaves the quiet band, 0–1. */
+    warnAt?: number;
+    /** Fraction at which the ring turns to the error colour, 0–1. */
+    criticalAt?: number;
+    /** Accessible name for the meter — what this ring is measuring. */
+    label?: string;
+    /** Whether clicking the ring opens a popover listing `usage.breakdown`. */
+    expandable?: boolean;
+    /** Additional CSS classes */
+    className?: string;
+    /**
+     * Plays the matching interface cue through the sound controller. Off by
+     * default; only audible once the user has enabled sound.
+     */
+    sound?: boolean;
+}
+/**
+ * ContextRing
+ */
+export declare const ContextRing: import("react").ForwardRefExoticComponent<ContextRingProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/components/context-ring/ContextRing.js

@@ -0,0 +1,257 @@
+"use client";
+import { jsxs, Fragment, jsx } from "react/jsx-runtime";
+import { forwardRef, useRef, useState, useCallback, useEffect } from "react";
+import { cn } from "../../utils.js";
+import { useComposedRefs } from "../../internals/dom/use-composed-refs.js";
+import { useElementRef } from "../../internals/dom/use-element-ref.js";
+import { useIsomorphicLayoutEffect } from "../../internals/dom/ssr.js";
+import { useFancyId } from "../../internals/use-id.js";
+import { useFloat } from "../../internals/use-float.js";
+import { useSoundCue } from "../../sound/use-sound.js";
+/* empty css                 */
+const NO_BREAKDOWN = "No breakdown reported.";
+function clamp(value, min, max) {
+  return Math.max(min, Math.min(value, max));
+}
+function fractionProp(value, fallback) {
+  return Number.isFinite(value) ? clamp(value, 0, 1) : fallback;
+}
+function compact(value) {
+  if (!Number.isFinite(value)) return "0";
+  const n = Math.max(0, Math.round(value));
+  if (n < 1e3) return String(n);
+  if (n < 1e5) {
+    const fixed = (n / 1e3).toFixed(1);
+    return `${fixed.endsWith(".0") ? fixed.slice(0, -2) : fixed}k`;
+  }
+  return `${Math.round(n / 1e3)}k`;
+}
+function grouped(value) {
+  return Math.max(0, Math.round(Number.isFinite(value) ? value : 0)).toLocaleString("en-US");
+}
+const ContextRing = forwardRef(function ContextRing2({
+  usage,
+  size = 28,
+  strokeWidth = 3,
+  showLabel = true,
+  warnAt = 0.75,
+  criticalAt = 0.9,
+  label = "Context usage",
+  expandable = false,
+  className,
+  sound = false
+}, forwardedRef) {
+  const uid = useFancyId();
+  const panelId = `${uid}-breakdown`;
+  const rootRef = useRef(null);
+  const composedRootRef = useComposedRefs(forwardedRef, rootRef);
+  const playCue = useSoundCue(sound);
+  const used = Number.isFinite(usage.used) ? Math.max(0, usage.used) : 0;
+  const max = Number.isFinite(usage.max) && usage.max > 0 ? usage.max : 0;
+  const fraction = max > 0 ? Math.min(1, used / max) : 0;
+  const warn = fractionProp(warnAt, 0.75);
+  const critical = Math.max(warn, fractionProp(criticalAt, 0.9));
+  const band = fraction >= critical ? "critical" : fraction >= warn ? "warn" : "ok";
+  const labelText = `${compact(used)} / ${compact(max)}`;
+  const valueNow = Math.round(Math.min(used, max));
+  const valueMax = Math.round(max);
+  const valueText = `${grouped(used)} of ${grouped(max)} tokens`;
+  const rows = usage.breakdown ?? [];
+  const px = Number.isFinite(size) ? Math.max(8, size) : 28;
+  const stroke = clamp(
+    Number.isFinite(strokeWidth) ? strokeWidth : 3,
+    0.5,
+    Math.max(0.5, px / 2 - 0.5)
+  );
+  const centre = px / 2;
+  const radius = Math.max(0.5, (px - stroke) / 2);
+  const circumference = 2 * Math.PI * radius;
+  const [filled, setFilled] = useState(false);
+  const sweep = filled ? fraction : 0;
+  const dashOffset = circumference * (1 - sweep);
+  useIsomorphicLayoutEffect(() => {
+    if (window.matchMedia("(prefers-reduced-motion: reduce)").matches) {
+      setFilled(true);
+      return;
+    }
+    let second = 0;
+    const first = requestAnimationFrame(() => {
+      second = requestAnimationFrame(() => {
+        setFilled(true);
+      });
+    });
+    return () => {
+      cancelAnimationFrame(first);
+      cancelAnimationFrame(second);
+    };
+  }, []);
+  const [open, setOpen] = useState(false);
+  const triggerRef = useRef(null);
+  const openRef = useRef(false);
+  const close = useCallback(() => {
+    if (!openRef.current) return;
+    openRef.current = false;
+    setOpen(false);
+    playCue("close");
+  }, [playCue]);
+  const toggle = useCallback(() => {
+    if (!openRef.current) {
+      openRef.current = true;
+      setOpen(true);
+      playCue("open");
+      return;
+    }
+    close();
+  }, [close, playCue]);
+  useEffect(() => {
+    if (!expandable) {
+      openRef.current = false;
+      setOpen(false);
+    }
+  }, [expandable]);
+  useEffect(() => {
+    if (!open) return;
+    const onKeydown = (event) => {
+      if (event.key !== "Escape") return;
+      close();
+      triggerRef.current?.focus();
+    };
+    const onPointerDown = (event) => {
+      const target = event.target;
+      if (target && rootRef.current?.contains(target)) return;
+      close();
+    };
+    window.addEventListener("keydown", onKeydown);
+    window.addEventListener("pointerdown", onPointerDown, true);
+    return () => {
+      window.removeEventListener("keydown", onKeydown);
+      window.removeEventListener("pointerdown", onPointerDown, true);
+    };
+  }, [open, close]);
+  const anchor = useCallback(
+    () => triggerRef.current?.getBoundingClientRect() ?? null,
+    []
+  );
+  const [panelEl, panelRef] = useElementRef();
+  useFloat(panelEl, { anchor, placement: "bottom-end", offset: 8 });
+  const face = /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx(
+      "span",
+      {
+        className: "ft-ctxring-meter inline-flex flex-none",
+        role: "meter",
+        "aria-label": label,
+        "aria-valuenow": valueNow,
+        "aria-valuemin": 0,
+        "aria-valuemax": valueMax,
+        "aria-valuetext": valueText,
+        children: /* @__PURE__ */ jsxs(
+          "svg",
+          {
+            className: "ft-ctxring-ring",
+            viewBox: `0 0 ${px} ${px}`,
+            style: { width: `${px}px`, height: `${px}px` },
+            "aria-hidden": "true",
+            children: [
+              /* @__PURE__ */ jsx(
+                "circle",
+                {
+                  className: "ft-ctxring-track",
+                  cx: centre,
+                  cy: centre,
+                  r: radius,
+                  fill: "none",
+                  strokeWidth: stroke
+                }
+              ),
+              /* @__PURE__ */ jsx(
+                "circle",
+                {
+                  className: cn(
+                    "ft-ctxring-value",
+                    band === "ok" && "ft-status-pending",
+                    band === "warn" && "ft-status-running",
+                    band === "critical" && "ft-status-error"
+                  ),
+                  cx: centre,
+                  cy: centre,
+                  r: radius,
+                  fill: "none",
+                  strokeWidth: stroke,
+                  strokeLinecap: "round",
+                  strokeDasharray: circumference,
+                  strokeDashoffset: dashOffset,
+                  transform: `rotate(-90 ${centre} ${centre})`
+                }
+              )
+            ]
+          }
+        )
+      }
+    ),
+    showLabel && /* @__PURE__ */ jsx("span", { className: "ft-ctxring-label text-foreground/70 text-xs tabular-nums", "aria-hidden": "true", children: labelText })
+  ] });
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      ref: composedRootRef,
+      className: cn("ft-ctxring inline-flex items-center gap-2", className),
+      "data-band": band,
+      children: [
+        expandable ? (
+          /*
+           * An explicit `aria-label`, because a button flattens everything inside it
+           * to presentational: the `role="meter"` and its value below never reach
+           * assistive tech once they are nested here. The button's own name carries
+           * both the meter's name and its current reading instead.
+           */
+          /* @__PURE__ */ jsx(
+            "button",
+            {
+              ref: triggerRef,
+              type: "button",
+              className: "ft-ctxring-trigger hover:bg-foreground/5 focus-visible:ring-ring -mx-1 -my-0.5 inline-flex items-center gap-2 rounded-md px-1 py-0.5 transition-colors focus-visible:ring-2 focus-visible:outline-none",
+              "aria-expanded": open,
+              "aria-controls": panelId,
+              "aria-label": `${label}, ${valueText}`,
+              onClick: toggle,
+              children: face
+            }
+          )
+        ) : face,
+        expandable && open && /*
+        * Rendered only while it is on screen: a breakdown that lives in the DOM
+        * permanently is a hidden list every screen-reader element list has to
+        * step over. The anchor is read through a getter so the float re-measures
+        * the trigger on every scroll and resize tick rather than holding a stale
+        * rect.
+        */
+        /* @__PURE__ */ jsx(
+          "div",
+          {
+            ref: panelRef,
+            id: panelId,
+            role: "group",
+            "aria-label": `${label} breakdown`,
+            className: "ft-ctxring-panel z-50 rounded-lg border p-2 text-left text-xs shadow-lg",
+            children: rows.length > 0 ? /* @__PURE__ */ jsx("ul", { className: "flex flex-col gap-1", children: rows.map((row, i) => /* @__PURE__ */ jsxs(
+              "li",
+              {
+                className: "ft-ctxring-row flex items-baseline justify-between gap-4",
+                children: [
+                  /* @__PURE__ */ jsx("span", { className: "min-w-0 truncate", children: row.label }),
+                  " ",
+                  /* @__PURE__ */ jsx("span", { className: "ft-ctxring-row-value flex-none tabular-nums", children: compact(row.tokens) })
+                ]
+              },
+              `${row.label}#${i}`
+            )) }) : /* @__PURE__ */ jsx("p", { className: "ft-ctxring-empty italic", children: NO_BREAKDOWN })
+          }
+        )
+      ]
+    }
+  );
+});
+export {
+  ContextRing
+};

package/dist/components/context-ring/index.d.ts

@@ -0,0 +1,2 @@
+export { ContextRing } from "./ContextRing.js";
+export type { ContextRingProps } from "./ContextRing.js";

package/dist/components/copy-button/CopyButton.d.ts

@@ -0,0 +1,39 @@
+import { type ReactNode } from "react";
+import type { ButtonVariant, ButtonSize } from "../button/types.js";
+export interface CopyButtonProps {
+    /** The text written to the clipboard on activation */
+    value: string;
+    /** Idle label */
+    label?: string;
+    /** Label shown for `resetMs` after a successful copy */
+    copiedLabel?: string;
+    /** Label and announcement shown for `resetMs` after a failed copy */
+    errorLabel?: string;
+    /** How long the copied state holds before reverting, in milliseconds */
+    resetMs?: number;
+    /** Passed straight through to the underlying Button */
+    variant?: ButtonVariant;
+    /** Passed straight through to the underlying Button */
+    size?: ButtonSize;
+    /** Disables the button and blocks the copy */
+    disabled?: boolean;
+    /** Drops the visible label, moving it to `aria-label` instead */
+    iconOnly?: boolean;
+    /** Called with the value and whether the write actually succeeded */
+    onCopy?: (value: string, ok: boolean) => void;
+    /**
+     * Overrides the default icon + label content. The success/failure skins
+     * (border, background, text colour) and the disabled/copy wiring still
+     * apply — set `iconOnly` too if the custom content has no readable text,
+     * so the button keeps an accessible name.
+     */
+    children?: ReactNode;
+    /** Additional CSS classes */
+    className?: string;
+    /**
+     * Plays the matching interface cue through the sound controller. Off by
+     * default; only audible once the user has enabled sound.
+     */
+    sound?: boolean;
+}
+export declare const CopyButton: import("react").ForwardRefExoticComponent<CopyButtonProps & import("react").RefAttributes<HTMLButtonElement | HTMLAnchorElement>>;

package/dist/components/copy-button/CopyButton.js

@@ -0,0 +1,124 @@
+"use client";
+import { jsxs, jsx } from "react/jsx-runtime";
+import { forwardRef, useRef, useState, useEffect } from "react";
+import { cn } from "../../utils.js";
+import { useConstant } from "../../internals/dom/ssr.js";
+import { useCopy } from "../../internals/use-copy.js";
+import { sound } from "../../sound/sound.js";
+import { Button } from "../button/Button.js";
+import { StatusMorph } from "../status-morph/StatusMorph.js";
+/* empty css                */
+const COPY_ICON = /* @__PURE__ */ jsxs(
+  "svg",
+  {
+    className: "size-full",
+    viewBox: "0 0 24 24",
+    fill: "none",
+    stroke: "currentColor",
+    strokeWidth: "2",
+    strokeLinecap: "round",
+    strokeLinejoin: "round",
+    "aria-hidden": "true",
+    children: [
+      /* @__PURE__ */ jsx("rect", { x: "9", y: "9", width: "13", height: "13", rx: "2", ry: "2" }),
+      /* @__PURE__ */ jsx("path", { d: "M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" })
+    ]
+  }
+);
+const MORPH_STYLE = {
+  width: "1rem",
+  height: "1rem",
+  fontSize: "calc(1rem - 1px)",
+  "--ft-statusmorph-error": "var(--ft-status-error, light-dark(oklch(0.577 0.245 27.325), oklch(0.704 0.191 22.216)))"
+};
+const CopyButton = forwardRef(
+  function CopyButton2({
+    value,
+    label = "Copy",
+    copiedLabel = "Copied",
+    errorLabel = "Copy failed",
+    resetMs = 2e3,
+    variant = "outline",
+    size = "md",
+    disabled = false,
+    iconOnly = false,
+    onCopy,
+    children,
+    className,
+    sound: sound$1 = false
+  }, ref) {
+    const resetWindow = useConstant(() => resetMs);
+    const copyState = useCopy(resetWindow);
+    const attempt = useRef(0);
+    const [morphState, setMorphState] = useState("idle");
+    const hasChildren = Boolean(children);
+    const currentLabel = morphState === "error" ? errorLabel : copyState.copied ? copiedLabel : label;
+    const classes = cn(
+      "ft-copybtn",
+      copyState.copied && morphState !== "error" && "ft-copybtn--copied border",
+      morphState === "error" && "ft-copybtn--failed border",
+      className
+    );
+    async function handleClick() {
+      if (sound$1 && sound.enabled) void sound.unlock();
+      setMorphState("idle");
+      const mine = ++attempt.current;
+      const ok = await copyState.copy(value);
+      if (mine === attempt.current) {
+        setMorphState(ok ? "success" : "error");
+        if (sound$1) sound.play(ok ? "copy" : "error");
+      }
+      onCopy?.(value, ok);
+    }
+    useEffect(() => {
+      if (!hasChildren || morphState === "idle") return;
+      const timer = setTimeout(
+        () => {
+          setMorphState("idle");
+        },
+        resetWindow > 0 ? resetWindow : 1
+      );
+      return () => clearTimeout(timer);
+    }, [hasChildren, morphState, resetWindow]);
+    const statusIcon = /* @__PURE__ */ jsx(
+      StatusMorph,
+      {
+        state: morphState,
+        onStateChange: setMorphState,
+        tone: "semantic",
+        resetAfter: resetWindow > 0 ? resetWindow : 1,
+        labels: { success: copiedLabel, error: errorLabel },
+        idle: COPY_ICON,
+        style: MORPH_STYLE
+      }
+    );
+    return /* @__PURE__ */ jsxs(
+      Button,
+      {
+        ref,
+        variant,
+        size,
+        disabled,
+        label: iconOnly ? currentLabel : void 0,
+        className: classes,
+        iconStart: hasChildren ? void 0 : statusIcon,
+        onClick: handleClick,
+        children: [
+          children,
+          /* @__PURE__ */ jsx(
+            "span",
+            {
+              "aria-live": hasChildren ? morphState === "error" ? "assertive" : "polite" : void 0,
+              className: iconOnly || hasChildren ? "sr-only" : void 0,
+              children: currentLabel
+            }
+          )
+        ]
+      }
+    );
+  }
+);
+CopyButton.displayName = "CopyButton";
+export {
+  CopyButton
+};

package/dist/components/copy-button/index.d.ts

@@ -0,0 +1,2 @@
+export { CopyButton } from "./CopyButton.js";
+export type { CopyButtonProps } from "./CopyButton.js";

package/dist/components/date-picker/DatePicker.d.ts

@@ -0,0 +1,58 @@
+import type { WeekStartsOn } from "../../internals/calendar-core.js";
+export interface DatePickerProps {
+    /**
+     * The selected date, or `null` for none. Always a local-midnight `Date` —
+     * see the README.
+     *
+     * Controlled when passed (`null` included): the caller owns it and writes
+     * the value back from `onValueChange`. Left out entirely, the component
+     * keeps its own copy and still reports every change — the React spelling
+     * of the source's `$bindable(null)`.
+     */
+    value?: Date | null;
+    /** Called with the new value whenever a day is picked. */
+    onValueChange?: (value: Date | null) => void;
+    /** Earliest selectable day (inclusive), compared at day granularity. */
+    min?: Date;
+    /** Latest selectable day (inclusive), compared at day granularity. */
+    max?: Date;
+    /** 0 for Sunday, 1 for Monday. Defaults to 1, matching the mockup. */
+    weekStartsOn?: WeekStartsOn;
+    /** Blocks opening the panel; excluded from form submission. Overridden by a surrounding FormField. */
+    disabled?: boolean;
+    /** Marks the field required for the surrounding form. Overridden by a surrounding FormField. */
+    required?: boolean;
+    /** Drives the error border and `aria-invalid`. Overridden by a surrounding FormField. */
+    invalid?: boolean;
+    /** Element id. Overridden by a surrounding FormField's own `controlId`. */
+    id?: string;
+    /** Native `name` — when set, a hidden input carries the ISO date so the value participates in real form submission. */
+    name?: string;
+    /** Accessible name — for a control with no visible Label next to it. */
+    label?: string;
+    /** Shown in the trigger while no day is selected. */
+    placeholder?: string;
+    /** BCP 47 locale for month, weekday, day and trigger-label formatting. Defaults to the runtime's own locale. */
+    locale?: string;
+    /** Rejects individual days beyond `min`/`max` — e.g. weekends, holidays. */
+    isDateDisabled?: (date: Date) => boolean;
+    /** Additional CSS classes, merged onto the trigger button. */
+    className?: string;
+    /**
+     * Plays the matching interface cue through the sound controller. Off
+     * by default; only audible once the user has enabled sound.
+     */
+    sound?: boolean;
+}
+/**
+ * A calendar picker behind a combobox trigger, with a portalled, anchored
+ * panel and full roving-focus keyboard navigation over the day grid.
+ *
+ * The trigger button 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 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 DatePicker: import("react").ForwardRefExoticComponent<DatePickerProps & import("react").RefAttributes<HTMLButtonElement>>;