@yourrealm/sdk 0.0.0-alpha.1378.ce03c8dc

package/src/ui/components/silo-picker.tsx

@@ -0,0 +1,510 @@
+// The operator's half of `host.silo`: which Silo this app joins. The author
+// declared affordances (read the shared files, write them); this picks the
+// directory those affordances apply to.
+//
+// Creating one from inside the picker is the point, not a convenience: for an
+// app that joins a Silo on its own, creating IS the install step, and folding
+// it away would tax the common case with a page trip.
+
+import type { ComponentChildren, JSX } from "preact";
+import { useId } from "preact/hooks";
+import { useSignal } from "@preact/signals";
+import type { SiloGrants } from "../../schema/host.ts";
+import type { SiloOption } from "../install/adapter.ts";
+import { Badge } from "./badge.tsx";
+import { Button } from "./button.tsx";
+import { Input } from "./input.tsx";
+import { Label } from "./label.tsx";
+import {
+  CheckCircleIcon,
+  CheckIcon,
+  ClipboardIcon,
+  FolderSimpleIcon,
+  KeyIcon,
+  PlusIcon,
+  ShareNetworkIcon,
+  StackIcon,
+  WarningIcon,
+} from "./icons.tsx";
+
+// The volume affordance carries its mode, because read-vs-write is the one
+// thing on this screen an operator can judge at a glance.
+type Affordance = "network" | "volume:read" | "volume:readwrite" | "apiKey";
+
+const AFFORDANCE_META: Record<Affordance, { label: string; Icon: typeof StackIcon }> = {
+  network: { label: "Network", Icon: ShareNetworkIcon },
+  "volume:read": { label: "Read shared files", Icon: FolderSimpleIcon },
+  "volume:readwrite": { label: "Read + write shared files", Icon: FolderSimpleIcon },
+  apiKey: { label: "Shared key", Icon: KeyIcon },
+};
+
+function affordancesOf(ask: SiloGrants): Affordance[] {
+  const out: Affordance[] = [];
+  if (ask.network !== undefined) out.push("network");
+  if (ask.volume !== undefined) out.push(`volume:${ask.volume}`);
+  if (ask.apiKey !== undefined) out.push("apiKey");
+  return out;
+}
+
+/**
+ * Require-map entries this Silo doesn't currently offer (name absent, or
+ * published on a different port). Only computable when the host sent a
+ * directory - an absent `offered` means unknown, and unknown stays pickable;
+ * the server's install gate is authoritative either way.
+ */
+function missingRequires(ask: SiloGrants, silo: SiloOption): Array<{ name: string; port: number }> {
+  if (ask.network === undefined || ask.network === true) return [];
+  if (silo.offered === undefined) return [];
+  const missing: Array<{ name: string; port: number }> = [];
+  for (const [name, port] of Object.entries(ask.network)) {
+    if (silo.offered[name] !== port) missing.push({ name, port });
+  }
+  return missing;
+}
+
+interface Props {
+  /** The author's declared affordances - the descriptor's `data`. */
+  ask: SiloGrants;
+  /** Every Silo the Home knows; the picker narrows to `workerId`. */
+  silos: SiloOption[];
+  /** The worker this app will run on. Null until one is chosen. */
+  workerId: string | null;
+  kind: "single" | "system";
+  /** The chosen Silo's id. */
+  value: string | null;
+  onChange: (id: string | null) => void;
+  /** Absent when the host serves a fixed set - the create card stays out. */
+  onCreate?: (input: { name: string; containerPath?: string; hostPath?: string }) => Promise<void>;
+  /**
+   * Confirm an adopted Silo's setup command from here, so an operator who
+   * created one mid-install can finish it without leaving the install.
+   */
+  onAcknowledge?: (id: string) => Promise<void>;
+  disabled?: boolean;
+}
+
+export function SiloPicker({
+  ask,
+  silos,
+  workerId,
+  kind,
+  value,
+  onChange,
+  onCreate,
+  onAcknowledge,
+  disabled,
+}: Props) {
+  const creating = useSignal(false);
+  const newName = useSignal("");
+  const newPath = useSignal("");
+  // Managed vs adopted, the same choice the Silos page offers. Which one the
+  // operator wants is the one question a solo-app install has to ask anyway.
+  const adopt = useSignal(false);
+  const newHostPath = useSignal("");
+  const saving = useSignal(false);
+  const createError = useSignal<string | null>(null);
+  // Field ids aren't literals: an install screen can show a picker per app,
+  // and duplicate ids would point every label at the first input.
+  const uid = useId();
+
+  const chips = (
+    <div class="flex flex-wrap gap-1.5">
+      {affordancesOf(ask).map((a) => {
+        const { label, Icon } = AFFORDANCE_META[a];
+        return (
+          <Badge key={a} variant="outline" className="gap-1">
+            <Icon /> {label}
+          </Badge>
+        );
+      })}
+    </div>
+  );
+
+  // A Silo is a directory on one box, so an app that fans out across every
+  // worker can never be bound to one. The install refuses this combination
+  // server-side; say so here rather than render a control that can't help.
+  if (kind === "system") {
+    return (
+      <Frame chips={chips}>
+        <Note>This app runs on every worker, and a Silo lives on one.</Note>
+      </Frame>
+    );
+  }
+
+  if (workerId === null) {
+    return (
+      <Frame chips={chips}>
+        <Note>Pick a worker first. Silos live on one worker, so the choice narrows by it.</Note>
+      </Frame>
+    );
+  }
+
+  const onWorker = silos.filter((s) => s.workerId === workerId);
+
+  async function create() {
+    createError.value = null;
+    const name = newName.value.trim();
+    if (!name) {
+      createError.value = "Name is required.";
+      return;
+    }
+    if (newPath.value && !newPath.value.startsWith("/")) {
+      createError.value = "Mount path must be absolute.";
+      return;
+    }
+    const folder = newHostPath.value.trim();
+    if (adopt.value && !folder.startsWith("/")) {
+      createError.value = "Folder path must be absolute.";
+      return;
+    }
+    saving.value = true;
+    try {
+      await onCreate!({
+        name,
+        ...(newPath.value ? { containerPath: newPath.value } : {}),
+        ...(adopt.value ? { hostPath: folder } : {}),
+      });
+      creating.value = false;
+      newName.value = "";
+      newPath.value = "";
+      newHostPath.value = "";
+      adopt.value = false;
+    } catch (err) {
+      createError.value = (err as Error).message;
+    } finally {
+      saving.value = false;
+    }
+  }
+
+  return (
+    <Frame chips={chips}>
+      {onWorker.length === 0 && (
+        <Note>
+          {onCreate
+            ? "No Silos on this worker yet. Create the first one below."
+            : "No Silos on this worker."}
+        </Note>
+      )}
+
+      {onWorker.map((silo) => {
+        const selected = value === silo.id;
+        const missing = missingRequires(ask, silo);
+        // A selected-but-now-unmet Silo (edit flow, provider since removed)
+        // keeps its card active so the operator can switch away; the note
+        // still says what's missing.
+        const unpickable = missing.length > 0 && !selected;
+        return (
+          <div
+            key={silo.id}
+            class={[
+              "rounded-xl border transition-colors",
+              selected ? "border-text-body bg-surface-light" : "border-border bg-surface-tinted",
+            ].join(" ")}
+          >
+            <button
+              type="button"
+              disabled={disabled || unpickable}
+              data-silo-option={silo.id}
+              data-silo-name={silo.name}
+              data-silo-missing={
+                missing.length > 0 ? missing.map((m) => m.name).join(",") : undefined
+              }
+              aria-pressed={selected}
+              onClick={() => onChange(silo.id)}
+              class={[
+                "w-full text-left p-3",
+                disabled || unpickable ? "cursor-not-allowed opacity-60" : "cursor-pointer",
+              ].join(" ")}
+            >
+              <div class="flex items-start gap-3">
+                <StackIcon className="w-5 h-5 mt-0.5 shrink-0 text-text-body" />
+                <div class="flex-1 min-w-0">
+                  <div class="flex items-center gap-2">
+                    <span class="font-medium text-text-dark">{silo.name}</span>
+                    {selected && <CheckCircleIcon className="w-4 h-4 text-success" />}
+                  </div>
+                  <div class="mt-0.5 font-mono text-xs text-text-muted truncate">
+                    {silo.hostPath}
+                  </div>
+                </div>
+              </div>
+            </button>
+            {missing.length > 0 && (
+              <div
+                class="flex items-start gap-2 border-t border-border px-3 py-2 text-xs text-perm"
+                data-testid={`silo-missing-${silo.id}`}
+              >
+                <WarningIcon className="w-4 h-4 mt-0.5 shrink-0" />
+                <span>
+                  {missing.length === 1
+                    ? `Missing required service: ${missing[0]!.name} (port ${missing[0]!.port})`
+                    : `Missing required services: ${missing
+                        .map((m) => `${m.name} (port ${m.port})`)
+                        .join(", ")}`}
+                </span>
+              </div>
+            )}
+            {/* Selectable anyway: the operator may be about to run the command,
+                or may have run it somewhere Realm can't see. A warning is
+                honest about what we know; a disabled card would claim we
+                checked. */}
+            {silo.setupCommand && (
+              <SetupNotice
+                silo={silo}
+                command={silo.setupCommand}
+                onAcknowledge={onAcknowledge}
+                disabled={disabled ?? false}
+              />
+            )}
+          </div>
+        );
+      })}
+
+      {onCreate && (
+        <div
+          class={[
+            "rounded-xl border transition-colors",
+            creating.value ? "border-text-body bg-surface-light" : "border-dashed border-border",
+          ].join(" ")}
+        >
+          <button
+            type="button"
+            disabled={disabled}
+            data-testid="silo-create-toggle"
+            onClick={() => (creating.value = !creating.value)}
+            class={`w-full text-left p-3 ${disabled ? "cursor-not-allowed opacity-60" : "cursor-pointer"}`}
+          >
+            <div class="flex items-center gap-3">
+              <PlusIcon className="w-5 h-5 shrink-0 text-text-body" />
+              <span class="font-medium text-text-dark">Create a new Silo</span>
+            </div>
+          </button>
+
+          {creating.value && (
+            <div class="px-3 pb-3 flex flex-col gap-4">
+              <div class="flex flex-col gap-1.5">
+                <Label htmlFor={`${uid}-name`}>Name</Label>
+                <Input
+                  id={`${uid}-name`}
+                  data-testid="silo-new-name"
+                  placeholder="Media"
+                  value={newName.value}
+                  disabled={disabled || saving.value}
+                  onValueChange={(v) => (newName.value = v)}
+                />
+              </div>
+
+              <div class="flex flex-col gap-1.5">
+                <Label htmlFor={`${uid}-path`}>Mount path</Label>
+                <Input
+                  id={`${uid}-path`}
+                  data-testid="silo-new-path"
+                  placeholder="/silo"
+                  value={newPath.value}
+                  disabled={disabled || saving.value}
+                  onValueChange={(v) => (newPath.value = v)}
+                />
+                <p class="text-xs text-text-muted">Where every member mounts it.</p>
+              </div>
+
+              <div class="flex flex-col gap-1.5">
+                <span class="text-xs font-medium text-text-muted">Where it lives</span>
+                <div class="grid grid-cols-2 gap-2">
+                  <PathMode
+                    active={!adopt.value}
+                    onClick={() => (adopt.value = false)}
+                    testId="silo-new-managed"
+                    title="Let Realm manage it"
+                    detail="A new directory on the worker you picked"
+                    disabled={disabled || saving.value}
+                  />
+                  <PathMode
+                    active={adopt.value}
+                    onClick={() => (adopt.value = true)}
+                    testId="silo-new-adopt"
+                    title="Use a folder I already have"
+                    detail="Point it at an existing directory"
+                    disabled={disabled || saving.value}
+                  />
+                </div>
+              </div>
+
+              {adopt.value ? (
+                <div class="flex flex-col gap-1.5">
+                  <Label htmlFor={`${uid}-host-path`}>Folder path</Label>
+                  <Input
+                    id={`${uid}-host-path`}
+                    data-testid="silo-new-host-path"
+                    placeholder="/mnt/nas/media"
+                    value={newHostPath.value}
+                    disabled={disabled || saving.value}
+                    onValueChange={(v) => (newHostPath.value = v)}
+                  />
+                  <p class="text-xs text-text-muted">
+                    Realm won't touch this folder. It picks a group for the Silo and gives you one
+                    command to run on the worker that hands the folder to it.
+                  </p>
+                </div>
+              ) : (
+                <p class="text-xs text-text-muted">
+                  Realm creates the directory itself, under{" "}
+                  <span class="font-mono">/opt/realm/worker/silo/&lt;generated&gt;</span>, and sets
+                  its group up for you.
+                </p>
+              )}
+
+              {createError.value && <p class="text-xs text-danger">{createError.value}</p>}
+
+              <Button
+                size="sm"
+                className="self-start"
+                disabled={disabled || saving.value}
+                data-testid="silo-create-submit"
+                onClick={create}
+              >
+                {saving.value ? "Creating…" : "Create and select"}
+              </Button>
+            </div>
+          )}
+        </div>
+      )}
+    </Frame>
+  );
+}
+
+function PathMode({
+  active,
+  onClick,
+  testId,
+  title,
+  detail,
+  disabled,
+}: {
+  active: boolean;
+  onClick: () => void;
+  testId: string;
+  title: string;
+  detail: string;
+  disabled: boolean;
+}) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      disabled={disabled}
+      aria-pressed={active}
+      data-testid={testId}
+      class={[
+        "rounded-xl border px-3 py-2 text-left transition-colors",
+        disabled ? "cursor-not-allowed opacity-60" : "cursor-pointer",
+        active ? "border-text-body bg-surface-light" : "border-border bg-surface-tinted",
+      ].join(" ")}
+    >
+      <div class="text-xs font-medium text-text-dark">{title}</div>
+      <div class="text-[11px] text-text-muted">{detail}</div>
+    </button>
+  );
+}
+
+// An adopted Silo the operator hasn't confirmed. It stays pickable, so the job
+// here is to say what the install can't guarantee - and to carry the command, so
+// creating a Silo mid-install can be finished in place rather than sending the
+// operator to another page with a half-filled form behind them.
+function SetupNotice({
+  silo,
+  command,
+  onAcknowledge,
+  disabled,
+}: {
+  silo: SiloOption;
+  command: string;
+  onAcknowledge?: (id: string) => Promise<void>;
+  disabled: boolean;
+}) {
+  const copied = useSignal(false);
+  const saving = useSignal(false);
+  const failed = useSignal<string | null>(null);
+
+  async function copy() {
+    await navigator.clipboard.writeText(command);
+    copied.value = true;
+    setTimeout(() => (copied.value = false), 1500);
+  }
+
+  async function acknowledge() {
+    failed.value = null;
+    saving.value = true;
+    try {
+      await onAcknowledge!(silo.id);
+    } catch (err) {
+      failed.value = (err as Error).message;
+    } finally {
+      saving.value = false;
+    }
+  }
+
+  return (
+    <div
+      class="flex flex-col gap-2 border-t border-border bg-perm-bg px-3 py-2.5"
+      data-testid={`silo-setup-${silo.id}`}
+      data-silo-setup-command={command}
+    >
+      <div class="flex items-start gap-2 text-xs text-perm">
+        <WarningIcon className="w-4 h-4 mt-0.5 shrink-0" />
+        <span>Setup command not confirmed yet - this app may not be able to read it.</span>
+      </div>
+      <pre class="overflow-x-auto rounded-lg bg-surface-tinted px-2.5 py-2 font-mono text-[11px] whitespace-pre text-text-body">
+        {command}
+      </pre>
+      <p class="text-[11px] text-text-muted">
+        Run it as root on {silo.workerSlug}. It changes the group of the folder and everything
+        inside it to {silo.gid}, so anything else reading that folder - a Samba share, a backup
+        script - needs adding to that group too. On a large library the recursive walk can run for a
+        long time; start it detached.
+      </p>
+      {failed.value && <p class="text-[11px] text-danger">{failed.value}</p>}
+      <div class="flex items-center gap-2">
+        <Button
+          size="sm"
+          variant="ghost"
+          disabled={disabled}
+          onClick={copy}
+          data-testid={`silo-setup-copy-${silo.id}`}
+        >
+          {copied.value ? <CheckIcon /> : <ClipboardIcon />}
+          {copied.value ? "Copied" : "Copy"}
+        </Button>
+        {onAcknowledge && (
+          <Button
+            size="sm"
+            disabled={disabled || saving.value}
+            onClick={acknowledge}
+            data-testid={`silo-setup-ack-${silo.id}`}
+          >
+            {saving.value ? "Saving…" : "I've run this"}
+          </Button>
+        )}
+      </div>
+    </div>
+  );
+}
+
+function Frame({ chips, children }: { chips: JSX.Element; children: ComponentChildren }) {
+  return (
+    <div class="mt-3 flex flex-col gap-2" data-slot="silo-picker">
+      <div class="flex items-baseline justify-between gap-3">
+        <span class="text-xs font-medium text-text-muted">Which Silo?</span>
+        {chips}
+      </div>
+      {children}
+    </div>
+  );
+}
+
+function Note({ children }: { children: ComponentChildren }) {
+  return (
+    <p class="rounded-xl border border-dashed border-border bg-surface-tinted px-3 py-2.5 text-xs text-text-body">
+      {children}
+    </p>
+  );
+}

package/src/ui/components/skeleton.tsx

@@ -0,0 +1,13 @@
+import { cn, type ElementProps } from "../utils.ts";
+
+function Skeleton({ className, ...props }: ElementProps<"div">) {
+  return (
+    <div
+      data-slot="skeleton"
+      className={cn("animate-pulse rounded-xl bg-muted", className)}
+      {...props}
+    />
+  );
+}
+
+export { Skeleton };

package/src/ui/components/sonner.tsx

@@ -0,0 +1,33 @@
+import type { JSX } from "preact";
+import { useTheme } from "next-themes";
+import { Toaster as Sonner, toast, type ToasterProps } from "sonner";
+
+const Toaster = ({ ...props }: ToasterProps) => {
+  const { theme = "system" } = useTheme();
+
+  return (
+    <Sonner
+      theme={theme as ToasterProps["theme"]}
+      className="toaster group"
+      toastOptions={{
+        classNames: {
+          toast: "rounded-2xl! shadow-lg! border-none! bg-card! text-card-foreground!",
+          title: "font-semibold!",
+          description: "text-muted-foreground!",
+          actionButton: "bg-primary! text-primary-foreground! rounded-xl! font-semibold!",
+          cancelButton: "bg-muted! text-muted-foreground! rounded-xl! font-semibold!",
+        },
+      }}
+      style={
+        {
+          "--normal-bg": "var(--card)",
+          "--normal-text": "var(--card-foreground)",
+          "--normal-border": "transparent",
+        } as JSX.CSSProperties
+      }
+      {...props}
+    />
+  );
+};
+
+export { Toaster, toast };

package/src/ui/components/switch.tsx

@@ -0,0 +1,58 @@
+import type { ComponentProps } from "preact";
+import { Switch as SwitchPrimitive } from "@ark-ui/react/switch";
+
+import { cn } from "../utils.ts";
+
+/**
+ * The switch names itself. Ark's machine points the hidden input's
+ * `aria-labelledby` at the label part whether or not it is mounted, so `label`
+ * is what gives the control an accessible name - and it is the visible name
+ * too, unless `labelClassName` hides it. A caller's own `<label htmlFor>` is
+ * fine as a click target; it does not name the control.
+ */
+function Switch({
+  className,
+  id,
+  label,
+  labelClassName,
+  ...props
+}: ComponentProps<typeof SwitchPrimitive.Root> & {
+  id?: string;
+  label?: string;
+  labelClassName?: string;
+}) {
+  return (
+    <SwitchPrimitive.Root
+      ids={id ? { hiddenInput: id } : undefined}
+      data-slot="switch"
+      className={cn(
+        "peer inline-flex shrink-0 cursor-pointer items-center gap-3 outline-none data-disabled:cursor-not-allowed data-disabled:opacity-50",
+        className,
+      )}
+      {...props}
+    >
+      {/* Focus lands on the hidden input, so the ring has to key off the
+          `data-focus-visible` Zag mirrors onto every part, not `:focus-visible`. */}
+      <SwitchPrimitive.Control
+        data-slot="switch-control"
+        className="inline-flex h-[26px] w-11 shrink-0 items-center rounded-full transition-all duration-250 data-[focus-visible]:ring-3 data-[focus-visible]:ring-ring/50 data-[state=checked]:bg-primary data-[state=checked]:shadow-clay-primary data-[state=unchecked]:bg-border data-[state=unchecked]:shadow-sm"
+      >
+        <SwitchPrimitive.Thumb
+          data-slot="switch-thumb"
+          className="pointer-events-none block size-5 rounded-full bg-white shadow-md transition-transform duration-250 data-[state=checked]:translate-x-[calc(100%-2px)] data-[state=unchecked]:translate-x-[3px]"
+        />
+      </SwitchPrimitive.Control>
+      {label !== undefined && (
+        <SwitchPrimitive.Label
+          data-slot="switch-label"
+          className={cn("text-sm leading-none font-medium select-none", labelClassName)}
+        >
+          {label}
+        </SwitchPrimitive.Label>
+      )}
+      <SwitchPrimitive.HiddenInput />
+    </SwitchPrimitive.Root>
+  );
+}
+
+export { Switch };