Custom persistence adapter — kloq React calendar

Two tenants, two calendars. Move something for acme, switch to globex, switch back: the move is still there, and globex never saw it. Reload the tab and both survive; close the tab and both are gone — that is sessionStorage's contract, and exactly what a docs page should leave behind. Clear this tenant wipes one copy and restarts it from its seeds.

liveCustom persistence adapter

acmeglobex

sessionStorage · kloq-example:acme:events

All day

"use client";

import { useMemo, useState } from "react";
import { Kloq } from "kloq";
import { Button } from "@/components/ui/button";
import { SegmentedControl, SegmentedControlItem } from "@/components/ui/segmented-control";
import { Bar } from "../parts";
import { seedsFor, sessionAdapter, storageKey, TENANTS, type Tenant } from "./data";

export default function CustomPersistenceExample() {
  const [tenant, setTenant] = useState<Tenant>("acme");
  const [generation, setGeneration] = useState(0);
  const adapter = useMemo(() => sessionAdapter(tenant), [tenant]);
  const seeds = useMemo(() => seedsFor(tenant), [tenant]);

  const clear = () => {
    adapter.clear();
    setGeneration((n) => n + 1);
  };

  return (
    <div className="@container flex flex-col">
      <Bar>
        <SegmentedControl size="sm" aria-label="Tenant" value={tenant} onValueChange={setTenant}>
          {TENANTS.map((t) => (
            <SegmentedControlItem key={t} value={t}>
              {t}
            </SegmentedControlItem>
          ))}
        </SegmentedControl>
        <span className="min-w-0 wrap-anywhere">
          sessionStorage · <span className="text-foreground">{storageKey(tenant)}</span>
        </span>
        <Button size="xs" variant="outline" className="ms-auto" onClick={clear}>
          Clear this tenant
        </Button>
      </Bar>

      <div className="h-136">
        {/* the key remounts the store: a new tenant loads its own copy, a clear starts from seeds */}
        <Kloq
          key={`${tenant}:${generation}`}
          storage={`tenant-${tenant}`}
          persistence={adapter}
          defaultEvents={seeds}
          designMode={false}
        >
          <Kloq.Toolbar />
        </Kloq>
      </div>
    </div>
  );
}

import {
  buildSeedEvents,
  dateOnlyAfter,
  dateOnlyAt,
  instantAt,
  PAYLOAD_VERSION,
  readPayload,
  resolveView,
  type CalEvent,
  type PayloadV2,
  type PersistenceAdapter,
} from "kloq";

export const TENANTS = ["acme", "globex"] as const;
export type Tenant = (typeof TENANTS)[number];

export const storageKey = (tenant: Tenant) => `kloq-example:${tenant}:events`;

export interface TenantAdapter extends PersistenceAdapter {
  clear(): void;
}

/**
 * sessionStorage, one key per tenant. The payload is kloq's own versioned envelope
 * (`{ v: 2, events }`), so `readPayload` does the checking: an unknown version or a
 * corrupt copy reads as null — "nothing stored" — and the seeds stay.
 */
export function sessionAdapter(tenant: Tenant): TenantAdapter {
  const key = storageKey(tenant);
  return {
    load() {
      try {
        const raw = sessionStorage.getItem(key);
        return raw ? (readPayload(JSON.parse(raw))?.events ?? null) : null;
      } catch {
        return null;
      }
    },
    save(events) {
      const payload: PayloadV2 = { v: PAYLOAD_VERSION, events };
      try {
        sessionStorage.setItem(key, JSON.stringify(payload));
      } catch {
        // quota / private mode — the change still applies in memory
      }
    },
    clear() {
      sessionStorage.removeItem(key);
    },
  };
}

/** Each tenant starts from its own week, so a switch is visibly a different calendar. */
export function seedsFor(tenant: Tenant, now = new Date()): CalEvent[] {
  if (tenant === "acme") return buildSeedEvents(now);
  const week = resolveView("week", 1, now);
  const at = (day: number, hour: number, minute = 0) => instantAt(week, day, hour * 60 + minute);
  return [
    { id: "globex-allhands", title: "Globex all-hands", start: at(0, 10), end: at(0, 11), color: "emerald" },
    { id: "globex-inspection", title: "Cooling tower inspection", start: at(1, 14), end: at(1, 16), color: "amber", location: "Plant 3" },
    { id: "globex-hank", title: "1:1 with Hank", start: at(2, 9, 30), end: at(2, 10), color: "violet" },
    { id: "globex-supplier", title: "Supplier review", start: at(3, 13), end: at(3, 14, 30), color: "blue" },
    { id: "globex-offsite", title: "Offsite", allDay: true, start: dateOnlyAt(week, 4), end: dateOnlyAfter(week, 4), color: "rose" },
  ];
}

"use client";

import type { ComponentProps } from "react";
import { ChevronLeft, ChevronRight } from "lucide-react";
import { formatViewTitle, useIsClient, useKloq } from "kloq";
import { Button } from "@/components/ui/button";
import { cn } from "@/lib/utils";

/** The strip an example hangs its controls and readouts on; same box as `Kloq.Toolbar`. */
export function Bar({
  edge = "bottom",
  className,
  ...props
}: ComponentProps<"div"> & { edge?: "top" | "bottom" }) {
  return (
    <div
      {...props}
      className={cn(
        "flex min-h-11 shrink-0 flex-wrap items-center gap-x-4 gap-y-2 px-4 py-2.5 font-mono text-xs text-muted-foreground",
        edge === "bottom" ? "border-b" : "border-t",
        className,
      )}
    />
  );
}

export function Dot({ live, className, ...props }: ComponentProps<"span"> & { live?: boolean }) {
  return (
    <span
      aria-hidden
      {...props}
      className={cn(
        "size-1.5 shrink-0 rounded-full",
        live ? "bg-brand motion-safe:animate-pulse" : "bg-border",
        className,
      )}
    />
  );
}

/** Previous / next / today for a calendar whose view is fixed. Must render inside `<Kloq>`. */
export function Nav({ locale }: { locale?: string }) {
  const k = useKloq();
  const isClient = useIsClient();
  return (
    <div className="flex min-w-0 items-center gap-1">
      <Button variant="ghost" size="icon-xs" aria-label="Previous" onClick={() => k.step(-1)}>
        <ChevronLeft />
      </Button>
      <Button variant="ghost" size="icon-xs" aria-label="Next" onClick={() => k.step(1)}>
        <ChevronRight />
      </Button>
      <Button variant="ghost" size="xs" className={cn(k.atToday && "text-muted-foreground")} onClick={k.goToday}>
        Today
      </Button>
      <span className="ms-1 truncate text-sm font-medium text-foreground tabular-nums sm:text-xs">
        {isClient ? formatViewTitle(k.view, locale, { short: k.narrow }) : null}
      </span>
    </div>
  );
}

usespersistencestoragePersistenceAdapterreadPayload

How it works

persistence={adapter} hands the uncontrolled store a PersistenceAdapter: load runs once after mount and returns the stored events or null for "nothing stored, keep the seeds"; save receives the full array on every committed change, never mid-drag; clear is what Reset calls. The contract is on the Persistence page.
The payload is versioned, and kloq checks it. save writes { v: PAYLOAD_VERSION, events } — the same envelope the built-in localStorageAdapter uses — and load reads it back through readPayload, which validates every event and returns null for a version it does not know, a corrupt copy, or a non-empty payload that validates to nothing. A newer build's data, or a hand-edited key, can never blank the calendar.
Tenancy is two keys. sessionAdapter("acme") closes over kloq-example:acme:events, and storage="tenant-acme" gives kloq's own preference keys — theme, scheme, density, zoom — the same namespace (tenant-acme-density and so on). Both are per-tenant, so a switch is a different calendar in every respect.
Switching remounts. <Kloq key={tenant}> throws the internal store away and builds a new one from that tenant's defaultEvents, then load swaps in the stored copy before first paint. The clear button does the same with a generation counter after calling adapter.clear(), so the calendar comes back on its seeds instead of saving an empty array.
Why sessionStorage: it is scoped to the tab and evaporates with it, so an example can persist for real without leaving anything in a visitor's browser. For an app, localStorageAdapter("myapp:calendar") is the same adapter over the durable store.

Take it further

Over the network: load: () => fetch(url).then((r) => r.json()).then((p) => readPayload(p)?.events ?? null) and save: (events) => fetch(url, { method: "PUT", body: JSON.stringify({ v: PAYLOAD_VERSION, events }) }). load may return a promise; the seeds render until it resolves.
IndexedDB: the same two functions over get(key) / set(key, payload) from a helper like idb-keyval. Keep the envelope — the version lives in the data, not the key.
Per change instead of full array: pair the adapter with onCommit and send each KloqChange to your API while the adapter keeps a local copy for instant loads.