@yourrealm/sdk 0.0.0-alpha.1378.ce03c8dc

package/src/ui/components/permission-row.tsx

@@ -0,0 +1,262 @@
+import type { ComponentChildren } from "preact";
+import { useState } from "preact/hooks";
+import { ArrowSquareOutIcon, QuestionIcon, resolveIcon } from "./icons.tsx";
+import { Checkbox } from "./checkbox.tsx";
+import { Label } from "./label.tsx";
+import { Switch } from "./switch.tsx";
+import { Tooltip, TooltipTrigger, TooltipContent } from "./tooltip.tsx";
+import { permissionMeta, type PermissionKind } from "../../permissions.ts";
+
+const ICON_SIZE = "w-[22px] h-[22px]";
+
+// Pass the raw string verbatim. Coercion happens server-side via the
+// grantSchema (z.coerce.number()...), so an empty input stays empty and
+// gets rejected at sanitizeGrants time, not silently coerced to 0 here.
+// type="number" + min/max stay for browser-level steppers and validation
+// hints; the value still flows as a string.
+function PortInput({ value, onChange }: { value: string | number; onChange: (v: string) => void }) {
+  return (
+    <span className="bg-surface-light shadow-sm rounded-lg px-1.5 py-0.5 inline-flex ml-1.5">
+      <input
+        type="number"
+        value={value}
+        onChange={(e) => onChange(e.currentTarget.value)}
+        min={1}
+        max={65535}
+        className="bg-transparent border-none outline-none text-sm font-mono font-bold text-text-body w-[50px] text-center [appearance:textfield] [&::-webkit-inner-spin-button]:appearance-none"
+      />
+    </span>
+  );
+}
+
+function buildTitle(kind: PermissionKind, name: string, label?: string): string {
+  if (!label) return name;
+  // host.port renders the port number in a separate PortInput pill, so the
+  // title shouldn't repeat it.
+  if (kind === "host.port") return name;
+  return `${name} ${label}`;
+}
+
+function PermissionRow({
+  kind,
+  reason,
+  required,
+  checked,
+  onCheckedChange,
+  label,
+  port,
+  onPortChange,
+  control,
+  url,
+  choices,
+  selectedChoices,
+  onSelectedChoicesChange,
+  scopes,
+  networks,
+}: {
+  kind: PermissionKind;
+  reason: string;
+  /** Omit to hide the required/optional badge (e.g. when the parent
+   * optional section is toggled off and requirements don't apply). */
+  required?: boolean;
+  checked: boolean;
+  onCheckedChange: (v: boolean) => void;
+  label?: string;
+  port?: string | number;
+  onPortChange?: (v: string) => void;
+  /**
+   * Per-kind control rendered under the reason. One slot rather than a
+   * prop per kind, so a kind with a richer choice than a text field
+   * (host.silo's picker) doesn't teach this component - or the docs site
+   * that also renders it - what a Silo is.
+   */
+  control?: ComponentChildren;
+  url?: string;
+  /**
+   * Sub-capabilities the admin can toggle independently. Each entry
+   * carries a name, an optional per-choice reason shown next to the
+   * checkbox, and an optional `required` flag that locks the checkbox
+   * on (and hides it from the Select-all deselect behavior).
+   */
+  choices?: Array<{ name: string; reason?: string; required?: boolean }>;
+  /** Controlled list of which choice names are currently selected. */
+  selectedChoices?: string[];
+  onSelectedChoicesChange?: (next: string[]) => void;
+  scopes?: string[];
+  networks?: string[];
+}) {
+  const meta = permissionMeta(kind);
+  const danger = meta.danger === true;
+  const title = buildTitle(kind, meta.name, label);
+  const Icon = resolveIcon(meta.icon);
+
+  const [portValue, setPortValue] = useState<string | number>(port ?? "");
+
+  const handlePortChange = onPortChange ?? setPortValue;
+  const currentPort = onPortChange ? (port ?? "") : portValue;
+
+  // Uncontrolled fallback: callers that pass `choices` without a matching
+  // `selectedChoices` + `onSelectedChoicesChange` pair (e.g. the docs-site
+  // PermissionPreview) still get a working toggle via internal state.
+  const [internalSelected, setInternalSelected] = useState<string[]>([]);
+  const isControlled = selectedChoices !== undefined && onSelectedChoicesChange !== undefined;
+  const effectiveSelected = isControlled ? (selectedChoices ?? []) : internalSelected;
+  const selectedSet = new Set(effectiveSelected);
+  const allNames = choices?.map((c) => c.name) ?? [];
+  const requiredSet = new Set(choices?.filter((c) => c.required === true).map((c) => c.name) ?? []);
+  const allChoicesSelected =
+    choices != null && choices.length > 0 && allNames.every((n) => selectedSet.has(n));
+
+  const emit = (next: string[]) => {
+    if (isControlled) onSelectedChoicesChange!(next);
+    else setInternalSelected(next);
+  };
+
+  const handleSelectAll = (v: boolean) => {
+    if (!choices) return;
+    // Deselect-all keeps required choices checked - they're locked and
+    // can't be turned off at the row level.
+    emit(v ? [...allNames] : allNames.filter((n) => requiredSet.has(n)));
+  };
+
+  const handleSelect = (choice: string, v: boolean) => {
+    if (!choices) return;
+    if (requiredSet.has(choice)) return; // locked, ignore attempts to toggle
+    const next = new Set(selectedSet);
+    if (v) next.add(choice);
+    else next.delete(choice);
+    emit(allNames.filter((n) => next.has(n)));
+  };
+
+  return (
+    <div className="bg-card rounded-2xl shadow p-3.5 px-4 flex items-start gap-3">
+      <span className={danger ? "text-danger" : "text-perm"}>
+        <Icon className={ICON_SIZE} />
+      </span>
+      <div className="flex-1 min-w-0">
+        <div className="flex items-center gap-2">
+          <h3 className={`text-sm font-bold ${danger ? "text-danger-deep" : "text-foreground"}`}>
+            {title}
+            {port != null && <PortInput value={currentPort} onChange={handlePortChange} />}
+          </h3>
+          {required !== undefined && (
+            <span
+              className={`text-[10px] font-bold px-[7px] py-0.5 rounded uppercase tracking-wide ${
+                danger ? "text-danger bg-danger-bg" : "text-muted-foreground bg-surface-light"
+              }`}
+            >
+              {required ? "required" : "optional"}
+            </span>
+          )}
+          <Tooltip>
+            <TooltipTrigger className="opacity-50 hover:opacity-100 transition-opacity">
+              <QuestionIcon
+                className={`w-[15px] h-[15px] ${danger ? "text-danger" : "text-perm"}`}
+              />
+            </TooltipTrigger>
+            <TooltipContent side="top" className="max-w-xs">
+              {meta.helpText}
+            </TooltipContent>
+          </Tooltip>
+        </div>
+        <p className="text-xs mt-1 leading-snug text-foreground">{reason}</p>
+        {control}
+        {scopes && scopes.length > 0 && (
+          <div className="flex gap-1.5 mt-1.5 flex-wrap">
+            {scopes.map((scope) => (
+              <span
+                key={scope}
+                className="text-[10px] font-mono font-semibold text-muted-foreground bg-surface-light px-2 py-0.5 rounded"
+              >
+                {scope}
+              </span>
+            ))}
+          </div>
+        )}
+        {networks && networks.length > 0 && (
+          <div className="flex gap-1.5 mt-1.5 flex-wrap">
+            {networks.map((net) => (
+              <span
+                key={net}
+                className="text-[10px] font-mono font-semibold text-muted-foreground bg-surface-light px-2 py-0.5 rounded"
+              >
+                {net}
+              </span>
+            ))}
+          </div>
+        )}
+        {url && (
+          <a
+            href={url}
+            target="_blank"
+            rel="noopener noreferrer"
+            className="text-[11px] mt-1 font-mono text-muted-foreground truncate block hover:underline group/url"
+          >
+            {url}
+            <ArrowSquareOutIcon className="w-3 h-3 inline ml-1 opacity-0 group-hover/url:opacity-100 transition-opacity" />
+          </a>
+        )}
+        {choices && (
+          <div className="flex flex-col gap-2 mt-3 pt-3 border-t border-border/50">
+            {choices.map((choice) => {
+              const isRequired = choice.required === true;
+              return (
+                <div key={choice.name} className="flex items-start gap-2">
+                  <Checkbox
+                    checked={isRequired || selectedSet.has(choice.name)}
+                    disabled={isRequired}
+                    onCheckedChange={(details: { checked: boolean | "indeterminate" }) =>
+                      handleSelect(choice.name, details.checked === true)
+                    }
+                    id={`perm-${choice.name}`}
+                    className="mt-0.5"
+                  />
+                  <div className="flex flex-col gap-0.5 min-w-0">
+                    <Label
+                      htmlFor={`perm-${choice.name}`}
+                      className={`text-xs ${isRequired ? "text-muted-foreground" : ""}`}
+                    >
+                      {choice.name}
+                      {isRequired && (
+                        <span className="ml-1.5 text-[10px] uppercase tracking-wide opacity-70">
+                          required
+                        </span>
+                      )}
+                    </Label>
+                    {choice.reason && (
+                      <p className="text-[11px] leading-snug text-muted-foreground">
+                        {choice.reason}
+                      </p>
+                    )}
+                  </div>
+                </div>
+              );
+            })}
+            {choices.some((c) => c.required !== true) && (
+              <div className="flex items-center gap-2">
+                <Checkbox
+                  checked={allChoicesSelected}
+                  onCheckedChange={(details: { checked: boolean | "indeterminate" }) =>
+                    handleSelectAll(details.checked === true)
+                  }
+                  id="perm-select-all"
+                />
+                <Label htmlFor="perm-select-all" className="text-xs text-muted-foreground">
+                  Select all
+                </Label>
+              </div>
+            )}
+          </div>
+        )}
+      </div>
+      <Switch
+        checked={checked}
+        onCheckedChange={(d: { checked: boolean }) => onCheckedChange(d.checked === true)}
+        label={title}
+        labelClassName="sr-only"
+      />
+    </div>
+  );
+}
+
+export { PermissionRow };

package/src/ui/components/permission-section.tsx

@@ -0,0 +1,51 @@
+import type { ComponentChildren } from "preact";
+import { ShieldIcon } from "./icons.tsx";
+import { cn } from "../utils.ts";
+
+function SectionLabel({
+  icon,
+  children,
+  className,
+}: {
+  icon?: ComponentChildren;
+  children: ComponentChildren;
+  className?: string;
+}) {
+  return (
+    <div
+      className={cn(
+        "text-[11px] font-bold text-muted-foreground uppercase tracking-wide flex items-center gap-1.5",
+        className,
+      )}
+    >
+      {icon}
+      {children}
+    </div>
+  );
+}
+
+function PermissionSection({
+  danger,
+  label,
+  children,
+}: {
+  danger?: boolean;
+  label?: ComponentChildren;
+  children: ComponentChildren;
+}) {
+  return (
+    <div
+      className={`${danger ? "bg-danger-bg rounded-3xl shadow-clay-danger" : "bg-perm-bg rounded-3xl shadow-clay-amber"} p-4 flex flex-col gap-3`}
+    >
+      <SectionLabel
+        icon={<ShieldIcon className={`w-4 h-4 ${danger ? "text-danger" : "text-perm"}`} />}
+        className={danger ? "text-danger" : "text-perm pl-0.5"}
+      >
+        {label ?? (danger ? "Dangerous permissions" : "Permissions")}
+      </SectionLabel>
+      {children}
+    </div>
+  );
+}
+
+export { PermissionSection, SectionLabel };

package/src/ui/components/pie-chart.tsx

@@ -0,0 +1,245 @@
+// Pie / donut chart. A stroke-dasharray ring: one <circle> per segment, drawn
+// as an arc by its dash length + accumulated offset, so there's no arc-path
+// math and no dependency. Colors default to the clay `--chart-*` palette, so it
+// themes with the surface (and flips in dark mode) — SVG references the CSS var
+// directly, no canvas, no redraw hook.
+//
+// Sizing: pass `size` for a fixed diameter, or omit it to fill the parent — it
+// measures the box and draws the largest square that fits (the center label is
+// font-scaled to the hole, so it grows with the donut). Pass `thickness` near
+// half the diameter for a solid pie. Opt into a `legend` and a hover `tooltip`
+// (dims the other slices, floats above the cursor); hovering a legend row
+// highlights its slice too.
+
+import type { ComponentChildren } from "preact";
+import { useLayoutEffect, useRef, useState } from "preact/hooks";
+import { cn } from "../utils.ts";
+
+export interface PieSegment {
+  label: string;
+  value: number;
+  /** Any CSS color; defaults to the `--chart-N` palette, cycled by index. */
+  color?: string;
+  /** Pre-formatted value for the legend + tooltip (e.g. "1.9 GB"). Falls back to `value`. */
+  valueLabel?: string;
+}
+
+const PALETTE = [
+  "var(--chart-1)",
+  "var(--chart-2)",
+  "var(--chart-3)",
+  "var(--chart-4)",
+  "var(--chart-5)",
+  "var(--chart-6)",
+  "var(--chart-7)",
+  "var(--chart-8)",
+];
+
+function colorOf(seg: PieSegment, i: number): string {
+  return seg.color ?? PALETTE[i % PALETTE.length]!;
+}
+
+interface PieChartProps {
+  data: PieSegment[];
+  /** Outer diameter in px. Omit to fill (and measure) the parent, staying square. */
+  size?: number;
+  /** Ring width in px. Default 20% of the diameter. Pass ~half the diameter for a solid pie. */
+  thickness?: number;
+  /** Big value in the hole (donut only). */
+  centerLabel?: ComponentChildren;
+  /** Caption under the center label. */
+  centerCaption?: ComponentChildren;
+  /** Ring shown behind the segments — the unfilled remainder reads as this. */
+  trackColor?: string;
+  /** Render a legend (dot + label + value) beside the donut. */
+  legend?: boolean;
+  /** Hover a slice → dim the others and float a tooltip above the cursor. */
+  tooltip?: boolean;
+  className?: string;
+}
+
+export function PieChart({
+  data,
+  size,
+  thickness,
+  centerLabel,
+  centerCaption,
+  trackColor = "var(--muted)",
+  legend = false,
+  tooltip = false,
+  className,
+}: PieChartProps) {
+  // Hover keyed by the segment's label, not its index: the loader swaps `data`
+  // out on a refetch (and may re-sort it), so an index would point at the wrong
+  // slice — or out of range — while the cursor rests. A label follows the slice.
+  const [hoveredLabel, setHoveredLabel] = useState<string | null>(null);
+  const [pos, setPos] = useState<{ x: number; y: number } | null>(null);
+  const rootRef = useRef<HTMLDivElement>(null);
+  const [box, setBox] = useState<{ w: number; h: number } | null>(null);
+  const responsive = size == null;
+
+  // Measure the fill container. useLayoutEffect fires before paint, so the first
+  // real frame already has a size — no empty flash.
+  useLayoutEffect(() => {
+    if (!responsive) return;
+    const el = rootRef.current;
+    if (!el) return;
+    const read = () => setBox({ w: el.clientWidth, h: el.clientHeight });
+    read();
+    const ro = new ResizeObserver(read);
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, [responsive]);
+
+  // Donut diameter: the fixed `size`, or the largest square that fits the
+  // measured parent — leaving half the width for the legend when there is one.
+  const s =
+    size ?? (box ? Math.max(0, Math.floor(Math.min(box.h, legend ? box.w * 0.5 : box.w))) : 0);
+
+  const w = thickness ?? s * 0.2;
+  const r = (s - w) / 2; // centerline radius, so the stroke stays inside the box
+  const hole = s - 2 * w; // inner diameter — the center label has to fit inside this
+  const circumference = 2 * Math.PI * r;
+  const c = s / 2;
+  const total = data.reduce((sum, d) => sum + Math.max(0, d.value), 0);
+  const hoverable = legend || tooltip;
+  const hovered = hoveredLabel != null ? data.findIndex((d) => d.label === hoveredLabel) : -1;
+  const active = hovered >= 0 ? data[hovered] : undefined;
+
+  let consumed = 0;
+  const donut = (
+    <div
+      class="relative shrink-0"
+      style={{ width: s, height: s }}
+      onPointerMove={tooltip ? (e) => setPos({ x: e.offsetX, y: e.offsetY }) : undefined}
+      onPointerLeave={
+        hoverable
+          ? () => {
+              setHoveredLabel(null);
+              setPos(null);
+            }
+          : undefined
+      }
+    >
+      <svg width={s} height={s} viewBox={`0 0 ${s} ${s}`}>
+        {/* rotate -90° around the center so segments start at 12 o'clock */}
+        <g transform={`rotate(-90 ${c} ${c})`}>
+          <circle
+            cx={c}
+            cy={c}
+            r={r}
+            fill="none"
+            stroke={trackColor}
+            stroke-width={w}
+            pointer-events="none"
+          />
+          {total > 0 &&
+            data.map((d, i) => {
+              const len = (Math.max(0, d.value) / total) * circumference;
+              const dash = (
+                <circle
+                  key={i}
+                  cx={c}
+                  cy={c}
+                  r={r}
+                  fill="none"
+                  stroke={colorOf(d, i)}
+                  stroke-width={w}
+                  stroke-dasharray={`${len} ${circumference - len}`}
+                  stroke-dashoffset={-consumed}
+                  opacity={hovered >= 0 && hovered !== i ? 0.3 : 1}
+                  style={{ transition: "opacity 120ms", cursor: hoverable ? "pointer" : undefined }}
+                  onPointerEnter={hoverable ? () => setHoveredLabel(d.label) : undefined}
+                />
+              );
+              consumed += len;
+              return dash;
+            })}
+        </g>
+      </svg>
+      {(centerLabel != null || centerCaption != null) && (
+        // Confined to the hole (inset by the ring width) and font-scaled to it,
+        // so the label always clears the ring instead of crowding it.
+        <div
+          class="absolute flex flex-col items-center justify-center gap-1 text-center"
+          style={{ inset: w, pointerEvents: "none" }}
+        >
+          {centerLabel != null && (
+            <div
+              class="font-semibold leading-none tabular-nums"
+              style={{ fontSize: Math.round(hole * 0.24) }}
+            >
+              {centerLabel}
+            </div>
+          )}
+          {centerCaption != null && (
+            <div
+              class="leading-none text-muted-foreground"
+              style={{ fontSize: Math.max(9, Math.round(hole * 0.13)) }}
+            >
+              {centerCaption}
+            </div>
+          )}
+        </div>
+      )}
+      {tooltip && active && pos && (
+        // Centered above the cursor (outer div positions, inner is the pill) with
+        // a caret pointing down at it — symmetric, so it rarely clips on an edge.
+        <div
+          class="pointer-events-none absolute z-10"
+          style={{ left: pos.x, top: pos.y, transform: "translate(-50%, calc(-100% - 10px))" }}
+        >
+          <div class="relative flex items-center gap-1.5 whitespace-nowrap rounded-md bg-foreground px-2.5 py-1.5 text-xs text-background">
+            <span
+              class="size-2 shrink-0 rounded-full"
+              style={{ background: colorOf(active, hovered) }}
+            />
+            <span class="font-medium">{active.label}</span>
+            <span class="tabular-nums text-background/70">{active.valueLabel ?? active.value}</span>
+            {total > 0 && (
+              <span class="tabular-nums text-background/50">
+                {Math.round((Math.max(0, active.value) / total) * 100)}%
+              </span>
+            )}
+            <span class="absolute left-1/2 top-full size-2 -translate-x-1/2 -translate-y-1/2 rotate-45 rounded-[2px] bg-foreground" />
+          </div>
+        </div>
+      )}
+    </div>
+  );
+
+  const rootClass = cn(
+    responsive
+      ? "flex h-full w-full items-center justify-center"
+      : legend
+        ? "flex items-center"
+        : "inline-block",
+    legend && "gap-4",
+    className,
+  );
+
+  return (
+    <div ref={responsive ? rootRef : undefined} class={rootClass} data-slot="pie-chart">
+      {s > 0 && donut}
+      {legend && s > 0 && (
+        <ul class="flex min-w-0 flex-col gap-1 text-xs">
+          {data.map((d, i) => (
+            <li
+              key={i}
+              class="flex items-center gap-1.5"
+              style={{ opacity: hovered >= 0 && hovered !== i ? 0.4 : 1 }}
+              onPointerEnter={() => setHoveredLabel(d.label)}
+              onPointerLeave={() => setHoveredLabel(null)}
+            >
+              <span class="size-2 shrink-0 rounded-full" style={{ background: colorOf(d, i) }} />
+              <span class="truncate">{d.label}</span>
+              <span class="ml-auto shrink-0 tabular-nums text-muted-foreground">
+                {d.valueLabel ?? d.value}
+              </span>
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}

package/src/ui/components/schema-block.tsx

@@ -0,0 +1,60 @@
+import type { ComponentChildren } from "preact";
+import { GearIcon } from "./icons.tsx";
+import { SectionLabel } from "./permission-section.tsx";
+import { Switch } from "./switch.tsx";
+
+// Visual chrome for an `r.tab(...)` block in the install/edit form.
+// Both Home's TabsForm and the docs site's SchemaPreviews render
+// through this so the two can't drift.
+export function TabBlock({ name, children }: { name: string; children: ComponentChildren }) {
+  return (
+    <section className="bg-trust-bg rounded-3xl shadow-clay-blue p-4 flex flex-col gap-3">
+      <SectionLabel
+        icon={<GearIcon className="w-4 h-4 text-trust" />}
+        className="text-trust pl-0.5"
+      >
+        {name}
+      </SectionLabel>
+      {children}
+    </section>
+  );
+}
+
+// Visual chrome for an `r.section(...)` block. Pass `optional` to render
+// the on/off toggle; controlled via `on` + `onChange`. Children are
+// always rendered regardless of `on` - the toggle only flips the section's
+// declared state, leaves keep showing so the user can still see what's
+// inside.
+export function SectionBlock({
+  name,
+  optional,
+  on,
+  onChange,
+  disabled,
+  children,
+}: {
+  name: string;
+  optional?: boolean;
+  on?: boolean;
+  onChange?: (next: boolean) => void;
+  disabled?: boolean;
+  children: ComponentChildren;
+}) {
+  return (
+    <fieldset className="bg-card rounded-2xl shadow p-4 flex flex-col gap-3">
+      <legend className="flex items-center gap-2 text-sm font-bold text-foreground px-1">
+        <span>{name}</span>
+        {optional && (
+          <Switch
+            checked={on === true}
+            onCheckedChange={(d: { checked: boolean }) => onChange?.(d.checked === true)}
+            disabled={disabled}
+            label={name}
+            labelClassName="sr-only"
+          />
+        )}
+      </legend>
+      {children}
+    </fieldset>
+  );
+}

package/src/ui/components/separator.tsx

@@ -0,0 +1,42 @@
+import { cn, type ElementProps } from "../utils.ts";
+
+function Separator({
+  className,
+  orientation = "horizontal",
+  children,
+  ...props
+}: ElementProps<"div"> & {
+  orientation?: "horizontal" | "vertical";
+}) {
+  if (children) {
+    return (
+      <div
+        data-slot="separator"
+        role="separator"
+        className={cn("flex items-center gap-4", className)}
+        {...props}
+      >
+        <div className="h-px flex-1 bg-gradient-to-r from-transparent to-border" />
+        <span className="text-sm font-bold uppercase tracking-wider text-muted-foreground">
+          {children}
+        </span>
+        <div className="h-px flex-1 bg-gradient-to-l from-transparent to-border" />
+      </div>
+    );
+  }
+
+  return (
+    <div
+      data-slot="separator"
+      role="separator"
+      data-orientation={orientation}
+      className={cn(
+        "shrink-0 data-[orientation=horizontal]:h-px data-[orientation=horizontal]:w-full data-[orientation=horizontal]:bg-gradient-to-r data-[orientation=horizontal]:from-transparent data-[orientation=horizontal]:via-border data-[orientation=horizontal]:to-transparent data-[orientation=vertical]:w-px data-[orientation=vertical]:self-stretch data-[orientation=vertical]:bg-border",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export { Separator };