@agent-native/scheduling 0.1.1

package/src/react/components/booking-links/DurationPicker.tsx

@@ -0,0 +1,115 @@
+/**
+ * DurationPicker — multi-select of booking durations rendered as pills.
+ *
+ * Bookers will pick between the selected durations on the public booking
+ * page (if more than one is selected). Shows 15/30/45/60 as default
+ * presets; the user can type an arbitrary number and add it too.
+ *
+ * Shadcn primitives expected in the consumer: button, input, label.
+ */
+import { useState } from "react";
+import { IconPlus, IconX } from "@tabler/icons-react";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+
+const DEFAULT_PRESETS = [15, 30, 45, 60];
+
+export interface DurationPickerProps {
+  value: number[];
+  onChange: (next: number[]) => void;
+  presets?: number[];
+  /** Minimum valid duration, defaults to 5 (minutes). */
+  min?: number;
+}
+
+function cls(...parts: (string | false | null | undefined)[]) {
+  return parts.filter(Boolean).join(" ");
+}
+
+export function DurationPicker(props: DurationPickerProps) {
+  const { value, onChange, presets = DEFAULT_PRESETS, min = 5 } = props;
+  const [custom, setCustom] = useState(15);
+
+  const toggle = (mins: number) => {
+    const next = value.includes(mins)
+      ? value.filter((d) => d !== mins)
+      : [...value, mins].sort((a, b) => a - b);
+    if (next.length === 0) return; // keep at least one
+    onChange(next);
+  };
+
+  const add = () => {
+    if (!custom || custom < min) return;
+    if (value.includes(custom)) return;
+    onChange([...value, custom].sort((a, b) => a - b));
+  };
+
+  const remove = (mins: number) => {
+    const next = value.filter((d) => d !== mins);
+    if (next.length === 0) return;
+    onChange(next);
+  };
+
+  // Union of presets + selected values → pill row.
+  const pillOptions = Array.from(new Set([...presets, ...value])).sort(
+    (a, b) => a - b,
+  );
+
+  return (
+    <div className="space-y-3">
+      <div className="flex flex-wrap gap-2">
+        {pillOptions.map((mins) => {
+          const isSelected = value.includes(mins);
+          const isCustom = !presets.includes(mins);
+          return (
+            <button
+              key={mins}
+              type="button"
+              onClick={() => toggle(mins)}
+              className={cls(
+                "inline-flex items-center gap-1 rounded-full border px-3 py-1.5 text-sm",
+                isSelected
+                  ? "border-primary bg-primary/10 text-primary"
+                  : "border-border text-muted-foreground hover:bg-accent/60 hover:text-foreground",
+              )}
+            >
+              {mins} min
+              {isSelected && isCustom && (
+                <span
+                  role="button"
+                  tabIndex={-1}
+                  onClick={(e) => {
+                    e.stopPropagation();
+                    remove(mins);
+                  }}
+                  className="rounded hover:bg-background"
+                >
+                  <IconX className="h-3 w-3" />
+                </span>
+              )}
+            </button>
+          );
+        })}
+      </div>
+      <div className="flex items-center gap-2">
+        <Input
+          type="number"
+          className="w-24"
+          value={custom}
+          onChange={(e) => setCustom(Number(e.currentTarget.value))}
+          min={min}
+        />
+        <span className="text-sm text-muted-foreground">minutes</span>
+        <Button size="sm" variant="outline" onClick={add}>
+          <IconPlus className="mr-1 h-3.5 w-3.5" />
+          Add
+        </Button>
+      </div>
+      {value.length > 1 && (
+        <p className="text-xs text-muted-foreground">
+          Bookers will choose between: {value.map((d) => `${d} min`).join(", ")}
+        </p>
+      )}
+    </div>
+  );
+}

package/src/react/components/booking-links/SlugEditor.tsx

@@ -0,0 +1,149 @@
+/**
+ * SlugEditor — inline-editable URL preview for a booking link.
+ *
+ * Renders the public booking URL as a single interactive line. Clicking
+ * the username segment (if editable) or the slug segment swaps it for an
+ * input; pressing Enter / blurring commits. All changes are fired through
+ * the `onUsernameChange` / `onSlugChange` callbacks synchronously — the
+ * caller owns persistence and should update UI optimistically.
+ *
+ * Shadcn primitives expected in the consumer: label.
+ */
+import { useState } from "react";
+import { Label } from "@/components/ui/label";
+
+export interface SlugEditorProps {
+  host: string;
+  /** Path prefix before the username, e.g. "/meet" (calendar) or "" (scheduling). */
+  pathPrefix?: string;
+  username: string;
+  slug: string;
+  onUsernameChange?: (next: string) => void;
+  onSlugChange: (next: string) => void;
+  /** Hide the top label (e.g. inside a compact inline row). */
+  hideLabel?: boolean;
+  /** Label text. Defaults to "URL". */
+  label?: string;
+}
+
+function slugify(value: string) {
+  return value
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+function cls(...parts: (string | false | null | undefined)[]) {
+  return parts.filter(Boolean).join(" ");
+}
+
+export function SlugEditor(props: SlugEditorProps) {
+  const {
+    host,
+    pathPrefix = "",
+    username,
+    slug,
+    onUsernameChange,
+    onSlugChange,
+    hideLabel,
+    label = "URL",
+  } = props;
+
+  const [editing, setEditing] = useState<"username" | "slug" | null>(null);
+  const [draft, setDraft] = useState("");
+
+  const startEdit = (field: "username" | "slug") => {
+    if (field === "username" && !onUsernameChange) return;
+    setEditing(field);
+    setDraft(field === "username" ? username : slug);
+  };
+
+  const commit = () => {
+    if (!editing) return;
+    const val = draft.trim();
+    if (val) {
+      if (editing === "username" && onUsernameChange) {
+        onUsernameChange(slugify(val));
+      } else if (editing === "slug") {
+        onSlugChange(slugify(val));
+      }
+    }
+    setEditing(null);
+  };
+
+  const prefix = pathPrefix ? `${pathPrefix}/` : "/";
+
+  return (
+    <div className="space-y-2">
+      {!hideLabel && <Label>{label}</Label>}
+      <div className="flex flex-wrap items-center gap-0 rounded-lg border border-border bg-muted/20 px-3 py-2 font-mono text-sm break-all">
+        <span className="text-muted-foreground">
+          {host}
+          {prefix}
+        </span>
+
+        {editing === "username" ? (
+          <input
+            autoFocus
+            value={draft}
+            onChange={(e) =>
+              setDraft(e.target.value.toLowerCase().replace(/[^a-z0-9-]/g, ""))
+            }
+            onBlur={commit}
+            onKeyDown={(e) => {
+              if (e.key === "Enter") commit();
+              if (e.key === "Escape") setEditing(null);
+            }}
+            className="inline-block bg-primary/10 text-primary border-b border-primary/40 outline-none px-0.5 py-0 font-mono text-sm w-auto min-w-[3ch]"
+            style={{ width: `${Math.max(3, draft.length)}ch` }}
+          />
+        ) : onUsernameChange ? (
+          <button
+            type="button"
+            onClick={() => startEdit("username")}
+            className={cls(
+              "inline rounded px-0.5 -mx-0.5 font-mono",
+              username
+                ? "text-foreground hover:bg-primary/10 hover:text-primary"
+                : "text-primary/60 bg-primary/5 border border-dashed border-primary/30 hover:bg-primary/10",
+            )}
+            title="Click to edit username"
+          >
+            {username || "your-name"}
+          </button>
+        ) : (
+          <span className="font-mono text-foreground">{username}</span>
+        )}
+
+        <span className="text-muted-foreground">/</span>
+
+        {editing === "slug" ? (
+          <input
+            autoFocus
+            value={draft}
+            onChange={(e) =>
+              setDraft(e.target.value.toLowerCase().replace(/[^a-z0-9-]/g, ""))
+            }
+            onBlur={commit}
+            onKeyDown={(e) => {
+              if (e.key === "Enter") commit();
+              if (e.key === "Escape") setEditing(null);
+            }}
+            className="inline-block bg-primary/10 text-primary border-b border-primary/40 outline-none px-0.5 py-0 font-mono text-sm w-auto min-w-[3ch]"
+            style={{ width: `${Math.max(3, draft.length)}ch` }}
+          />
+        ) : (
+          <button
+            type="button"
+            onClick={() => startEdit("slug")}
+            className="inline rounded px-0.5 -mx-0.5 font-mono text-foreground hover:bg-primary/10 hover:text-primary"
+            title="Click to edit slug"
+          >
+            {slug || "meeting"}
+          </button>
+        )}
+      </div>
+    </div>
+  );
+}

package/src/react/components/booking-links/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Shared booking-link / event-type UI components. Consumers:
+ *   - calendar template → app/pages/BookingLinksPage
+ *   - scheduling template → app/routes/_app.event-types.$id
+ *
+ * Every component here renders with the consumer's shadcn primitives
+ * imported via `@/components/ui/*`. See the top of each file for the
+ * list of primitives required.
+ */
+export * from "./AvailabilityEditor.js";
+export * from "./BookingLinkCreateDialog.js";
+export * from "./ConferencingSelector.js";
+export * from "./CustomFieldsEditor.js";
+export * from "./DurationPicker.js";
+export * from "./SlugEditor.js";

package/src/react/components/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Styled components for the scheduling package.
+ *
+ * These components import shadcn primitives from the consumer via the
+ * `@/components/ui/*` alias — the package doesn't bundle shadcn. See each
+ * component file for the list of primitives it expects.
+ *
+ * NOTE: In v0.1 the main `<Booker>` lives in the scheduling template first.
+ * Once its API stabilizes we hoist it here (v0.2).
+ */
+export * from "./SlotPicker.js";
+export * from "./TimezoneSelect.js";
+export * from "./booking-links/index.js";

package/src/react/hooks/useBookingFlow.ts

@@ -0,0 +1,113 @@
+/**
+ * useBookingFlow — the Booker state machine.
+ *
+ * Stages: "pick-date" → "pick-slot" → "fill-form" → "success"
+ * (plus "error" for any step's failure).
+ *
+ * Persistence: stores the current selection in a tuple that can be mirrored
+ * to URL query params and `application_state.booker-state` so both the agent
+ * and a page refresh see the same state.
+ */
+import { useState, useCallback } from "react";
+import type { Slot } from "../../shared/index.js";
+
+export type BookerStage =
+  | "pick-date"
+  | "pick-slot"
+  | "fill-form"
+  | "submitting"
+  | "success"
+  | "error";
+
+export interface BookerState {
+  stage: BookerStage;
+  selectedDate: string | null;
+  selectedSlot: Slot | null;
+  durationChoice: number | null;
+  form: {
+    name: string;
+    email: string;
+    notes: string;
+    customResponses: Record<string, any>;
+  };
+  error: string | null;
+  resultBookingUid: string | null;
+}
+
+export interface UseBookingFlowOpts {
+  initial?: Partial<BookerState>;
+  onStateChange?: (state: BookerState) => void;
+}
+
+export function useBookingFlow(opts: UseBookingFlowOpts = {}) {
+  const [state, setState] = useState<BookerState>(() => ({
+    stage: "pick-date",
+    selectedDate: null,
+    selectedSlot: null,
+    durationChoice: null,
+    form: { name: "", email: "", notes: "", customResponses: {} },
+    error: null,
+    resultBookingUid: null,
+    ...opts.initial,
+  }));
+
+  const update = useCallback(
+    (partial: Partial<BookerState>) => {
+      setState((s) => {
+        const next = { ...s, ...partial };
+        opts.onStateChange?.(next);
+        return next;
+      });
+    },
+    [opts.onStateChange],
+  );
+
+  const selectDate = useCallback(
+    (date: string) =>
+      update({ selectedDate: date, selectedSlot: null, stage: "pick-slot" }),
+    [update],
+  );
+  const selectSlot = useCallback(
+    (slot: Slot) => update({ selectedSlot: slot, stage: "fill-form" }),
+    [update],
+  );
+  const setForm = useCallback(
+    (patch: Partial<BookerState["form"]>) =>
+      update({ form: { ...state.form, ...patch } }),
+    [update, state.form],
+  );
+  const backToDate = useCallback(
+    () => update({ stage: "pick-date", selectedSlot: null }),
+    [update],
+  );
+  const backToSlot = useCallback(
+    () => update({ stage: "pick-slot" }),
+    [update],
+  );
+  const submitStart = useCallback(
+    () => update({ stage: "submitting" }),
+    [update],
+  );
+  const submitSuccess = useCallback(
+    (uid: string) =>
+      update({ stage: "success", resultBookingUid: uid, error: null }),
+    [update],
+  );
+  const submitError = useCallback(
+    (err: string) => update({ stage: "error", error: err }),
+    [update],
+  );
+
+  return {
+    state,
+    update,
+    selectDate,
+    selectSlot,
+    setForm,
+    backToDate,
+    backToSlot,
+    submitStart,
+    submitSuccess,
+    submitError,
+  };
+}

package/src/react/hooks/useEventType.ts

@@ -0,0 +1,52 @@
+/**
+ * useEventType — fetch one event type by id or slug via a consumer-provided
+ * callback (typically calling the `get-event-type` action).
+ */
+import { useEffect, useState } from "react";
+import type { EventType } from "../../shared/index.js";
+
+export interface UseEventTypeOpts {
+  id?: string;
+  slug?: string;
+  ownerEmail?: string;
+  teamId?: string;
+  fetchEventType: (params: {
+    id?: string;
+    slug?: string;
+    ownerEmail?: string;
+    teamId?: string;
+  }) => Promise<{ eventType: EventType | null }>;
+}
+
+export function useEventType(opts: UseEventTypeOpts) {
+  const [eventType, setEventType] = useState<EventType | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    setIsLoading(true);
+    opts
+      .fetchEventType({
+        id: opts.id,
+        slug: opts.slug,
+        ownerEmail: opts.ownerEmail,
+        teamId: opts.teamId,
+      })
+      .then((r) => {
+        if (cancelled) return;
+        setEventType(r.eventType);
+        setIsLoading(false);
+      })
+      .catch((err) => {
+        if (cancelled) return;
+        setError(err);
+        setIsLoading(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [opts.id, opts.slug, opts.ownerEmail, opts.teamId, opts.fetchEventType]);
+
+  return { eventType, isLoading, error };
+}

package/src/react/hooks/useReschedule.ts

@@ -0,0 +1,39 @@
+/**
+ * useReschedule — fetch an existing booking + drive the Booker through a
+ * reschedule flow that replaces its start/end time.
+ */
+import { useEffect, useState } from "react";
+import type { Booking } from "../../shared/index.js";
+
+export interface UseRescheduleOpts {
+  uid: string;
+  fetchBooking: (uid: string) => Promise<{ booking: Booking | null }>;
+}
+
+export function useReschedule(opts: UseRescheduleOpts) {
+  const [booking, setBooking] = useState<Booking | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    setIsLoading(true);
+    opts
+      .fetchBooking(opts.uid)
+      .then((r) => {
+        if (cancelled) return;
+        setBooking(r.booking);
+        setIsLoading(false);
+      })
+      .catch((err) => {
+        if (cancelled) return;
+        setError(err);
+        setIsLoading(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [opts.uid, opts.fetchBooking]);
+
+  return { booking, isLoading, error };
+}

package/src/react/hooks/useSlots.ts

@@ -0,0 +1,88 @@
+/**
+ * useSlots — fetches available time slots for an event type over a date
+ * range. Plays well with @tanstack/react-query when it's available, falls
+ * back to a plain fetch + state when not.
+ *
+ * The hook is transport-agnostic: consumers pass a `fetchSlots` callback
+ * that calls their own API (typically an action like `check-availability`).
+ */
+import { useEffect, useState, useCallback } from "react";
+import type { Slot } from "../../shared/index.js";
+
+export interface UseSlotsOpts {
+  eventTypeId?: string;
+  slug?: string;
+  ownerEmail?: string;
+  teamId?: string;
+  from: string;
+  to: string;
+  timezone?: string;
+  /** Consumer-provided fetch function — typically calls `check-availability` */
+  fetchSlots: (params: {
+    eventTypeId?: string;
+    slug?: string;
+    ownerEmail?: string;
+    teamId?: string;
+    from: string;
+    to: string;
+    timezone?: string;
+  }) => Promise<{ slots: Slot[] }>;
+  /** If false, don't fetch (e.g. waiting on a dependency) */
+  enabled?: boolean;
+}
+
+export interface UseSlotsResult {
+  slots: Slot[];
+  isLoading: boolean;
+  error: Error | null;
+  refetch: () => void;
+}
+
+export function useSlots(opts: UseSlotsOpts): UseSlotsResult {
+  const [slots, setSlots] = useState<Slot[]>([]);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const [tick, setTick] = useState(0);
+
+  const load = useCallback(async () => {
+    if (opts.enabled === false) return;
+    if (!opts.eventTypeId && !opts.slug) return;
+    setIsLoading(true);
+    setError(null);
+    try {
+      const result = await opts.fetchSlots({
+        eventTypeId: opts.eventTypeId,
+        slug: opts.slug,
+        ownerEmail: opts.ownerEmail,
+        teamId: opts.teamId,
+        from: opts.from,
+        to: opts.to,
+        timezone: opts.timezone,
+      });
+      setSlots(result.slots);
+    } catch (err) {
+      setError(err as Error);
+      setSlots([]);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [
+    opts.enabled,
+    opts.eventTypeId,
+    opts.slug,
+    opts.ownerEmail,
+    opts.teamId,
+    opts.from,
+    opts.to,
+    opts.timezone,
+    opts.fetchSlots,
+    tick,
+  ]);
+
+  useEffect(() => {
+    load();
+  }, [load]);
+
+  const refetch = useCallback(() => setTick((t) => t + 1), []);
+  return { slots, isLoading, error, refetch };
+}

package/src/react/hooks/useTimezone.ts

@@ -0,0 +1,29 @@
+/**
+ * Timezone hook — resolves the viewer's IANA timezone with `localStorage`
+ * persistence and a setter. Booker uses this to display slot times.
+ */
+import { useCallback, useEffect, useState } from "react";
+
+const KEY = "scheduling.timezone";
+
+export function detectBrowserTimezone(): string {
+  try {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+  } catch {
+    return "UTC";
+  }
+}
+
+export function useTimezone(): [string, (tz: string) => void] {
+  const [tz, setTz] = useState<string>(() => {
+    if (typeof window === "undefined") return "UTC";
+    return window.localStorage?.getItem(KEY) || detectBrowserTimezone();
+  });
+  useEffect(() => {
+    try {
+      window.localStorage?.setItem(KEY, tz);
+    } catch {}
+  }, [tz]);
+  const update = useCallback((next: string) => setTz(next), []);
+  return [tz, update];
+}

package/src/react/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Headless hooks for scheduling UIs. The stable API surface of the React
+ * entry point — components live at `@agent-native/scheduling/react/components`
+ * and are less stable until v1.0.
+ */
+export * from "./hooks/useTimezone.js";
+export * from "./hooks/useSlots.js";
+export * from "./hooks/useBookingFlow.js";
+export * from "./hooks/useEventType.js";
+export * from "./hooks/useReschedule.js";