@yourrealm/sdk 0.0.0-alpha.1378.ce03c8dc

package/src/ui/components/button.tsx

@@ -0,0 +1,59 @@
+import { cva, type VariantProps } from "class-variance-authority";
+
+import { cn, type ElementProps } from "../utils.ts";
+
+const buttonVariants = cva(
+  "cursor-pointer group/button inline-flex shrink-0 items-center justify-center text-sm font-bold whitespace-nowrap transition-all outline-none select-none focus-visible:ring-3 focus-visible:ring-ring/50 active:translate-y-px disabled:pointer-events-none disabled:opacity-50 aria-invalid:ring-3 aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+  {
+    variants: {
+      variant: {
+        default:
+          "bg-primary text-primary-foreground shadow-clay-primary hover:brightness-110 dark:shadow-clay-dark-primary",
+        outline:
+          "border-border bg-background shadow-sm hover:shadow hover:text-foreground aria-expanded:bg-muted aria-expanded:text-foreground dark:border-input dark:bg-input/30 dark:shadow-clay-dark-sm dark:hover:shadow-clay-dark",
+        secondary:
+          "bg-surface-light text-foreground shadow-sm hover:shadow aria-expanded:bg-surface-light aria-expanded:text-foreground dark:bg-secondary dark:shadow-clay-dark-sm dark:hover:shadow-clay-dark",
+        ghost:
+          "hover:bg-muted hover:text-foreground aria-expanded:bg-muted aria-expanded:text-foreground dark:hover:bg-muted/50",
+        destructive:
+          "bg-destructive/10 text-destructive shadow-clay-danger hover:bg-destructive/20 focus-visible:border-destructive/40 focus-visible:ring-destructive/20 dark:bg-destructive/20 dark:hover:bg-destructive/30 dark:focus-visible:ring-destructive/40",
+        link: "text-primary underline-offset-4 hover:underline",
+      },
+      size: {
+        default:
+          "gap-1.5 rounded-[10px] px-4 py-2 has-data-[icon=inline-end]:pr-3 has-data-[icon=inline-start]:pl-3",
+        xs: "gap-1 rounded-lg px-2.5 py-1 text-xs has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5 [&_svg:not([class*='size-'])]:size-3",
+        sm: "gap-1 rounded-[10px] px-3 py-1.5 text-[0.8rem] has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2 [&_svg:not([class*='size-'])]:size-3.5",
+        lg: "gap-2 rounded-2xl px-6 py-3.5 has-data-[icon=inline-end]:pr-4 has-data-[icon=inline-start]:pl-4",
+        xl: "gap-2 rounded-xl px-9 py-4 text-[15px] has-data-[icon=inline-end]:pr-6 has-data-[icon=inline-start]:pl-6",
+        icon: "size-9 rounded-[10px]",
+        "icon-xs": "size-6 rounded-lg [&_svg:not([class*='size-'])]:size-3",
+        "icon-sm": "size-7 rounded-[10px]",
+        "icon-lg": "size-11 rounded-xl",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  },
+);
+
+function Button({
+  className,
+  variant = "default",
+  size = "default",
+  type = "button",
+  ...props
+}: ElementProps<"button"> & VariantProps<typeof buttonVariants>) {
+  return (
+    <button
+      data-slot="button"
+      type={type}
+      className={cn(buttonVariants({ variant, size, className }))}
+      {...props}
+    />
+  );
+}
+
+export { Button, buttonVariants };

package/src/ui/components/card.tsx

@@ -0,0 +1,106 @@
+import { cva, type VariantProps } from "class-variance-authority";
+
+import { cn, type ElementProps } from "../utils.ts";
+
+const cardVariants = cva(
+  "group/card flex flex-col gap-4 overflow-hidden text-card-foreground has-data-[slot=card-footer]:pb-0 has-[>img:first-child]:pt-0 data-[size=sm]:gap-3 data-[size=sm]:has-data-[slot=card-footer]:pb-0",
+  {
+    variants: {
+      variant: {
+        default:
+          "rounded-2xl bg-card px-2 py-4 text-sm shadow *:[img:first-child]:rounded-t-2xl *:[img:last-child]:rounded-b-2xl data-[size=sm]:py-3",
+        glass: "rounded-3xl bg-card/35 backdrop-blur-xl shadow-xl",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+    },
+  },
+);
+
+type CardProps = ElementProps<"div"> &
+  VariantProps<typeof cardVariants> & {
+    size?: "default" | "sm";
+  };
+
+function Card({ className, size = "default", variant, ...props }: CardProps) {
+  return (
+    <div
+      data-slot="card"
+      data-size={size}
+      className={cn(cardVariants({ variant, className }))}
+      {...props}
+    />
+  );
+}
+
+function CardHeader({ className, ...props }: ElementProps<"div">) {
+  return (
+    <div
+      data-slot="card-header"
+      className={cn(
+        "group/card-header @container/card-header grid auto-rows-min items-start gap-1 rounded-t-2xl px-4 group-data-[size=sm]/card:px-3 has-data-[slot=card-action]:grid-cols-[1fr_auto] has-data-[slot=card-description]:grid-rows-[auto_auto] [.border-b]:pb-4 group-data-[size=sm]/card:[.border-b]:pb-3",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function CardTitle({ className, ...props }: ElementProps<"div">) {
+  return (
+    <div
+      data-slot="card-title"
+      className={cn(
+        "text-base leading-snug font-medium group-data-[size=sm]/card:text-sm",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function CardDescription({ className, ...props }: ElementProps<"div">) {
+  return (
+    <div
+      data-slot="card-description"
+      className={cn("text-sm text-muted-foreground", className)}
+      {...props}
+    />
+  );
+}
+
+function CardAction({ className, ...props }: ElementProps<"div">) {
+  return (
+    <div
+      data-slot="card-action"
+      className={cn("col-start-2 row-span-2 row-start-1 self-start justify-self-end", className)}
+      {...props}
+    />
+  );
+}
+
+function CardContent({ className, ...props }: ElementProps<"div">) {
+  return (
+    <div
+      data-slot="card-content"
+      className={cn("px-4 group-data-[size=sm]/card:px-3", className)}
+      {...props}
+    />
+  );
+}
+
+function CardFooter({ className, ...props }: ElementProps<"div">) {
+  return (
+    <div
+      data-slot="card-footer"
+      className={cn(
+        "flex items-center rounded-b-2xl border-t bg-muted/50 p-4 group-data-[size=sm]/card:p-3",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export { Card, CardHeader, CardFooter, CardTitle, CardAction, CardDescription, CardContent };

package/src/ui/components/checkbox.tsx

@@ -0,0 +1,37 @@
+import type { ComponentProps } from "preact";
+import { Checkbox as CheckboxPrimitive } from "@ark-ui/react/checkbox";
+
+import { cn } from "../utils.ts";
+import { CheckBoldIcon } from "./icons.tsx";
+
+function Checkbox({
+  className,
+  id,
+  ...props
+}: ComponentProps<typeof CheckboxPrimitive.Root> & { id?: string }) {
+  return (
+    <CheckboxPrimitive.Root
+      ids={id ? { hiddenInput: id } : undefined}
+      data-slot="checkbox"
+      className={cn(
+        // The root is a <label>; focus lands on the hidden input, so the ring
+        // has to key off the `data-focus-visible` Zag mirrors onto every part.
+        "cursor-pointer peer relative flex size-4 shrink-0 items-center justify-center rounded-[5px] border border-border bg-card shadow-sm transition-all outline-none group-has-disabled/field:opacity-50 after:absolute after:-inset-x-3 after:-inset-y-2 data-[focus-visible]:ring-3 data-[focus-visible]:ring-ring/50 disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:ring-3 aria-invalid:ring-destructive/20 dark:bg-input/30 dark:shadow-clay-dark-sm dark:aria-invalid:ring-destructive/40 data-[state=checked]:bg-primary data-[state=checked]:shadow-clay-primary data-[state=checked]:text-primary-foreground dark:data-[state=checked]:bg-primary dark:data-[state=checked]:shadow-clay-dark-primary",
+        className,
+      )}
+      {...props}
+    >
+      <CheckboxPrimitive.Control
+        data-slot="checkbox-indicator"
+        className="grid place-content-center text-current transition-none [&>svg]:size-3.5"
+      >
+        <CheckboxPrimitive.Indicator>
+          <CheckBoldIcon />
+        </CheckboxPrimitive.Indicator>
+      </CheckboxPrimitive.Control>
+      <CheckboxPrimitive.HiddenInput />
+    </CheckboxPrimitive.Root>
+  );
+}
+
+export { Checkbox };

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

@@ -0,0 +1,29 @@
+// Pure presentational component: renders pre-highlighted HTML. The Shiki-backed
+// highlightCode() lives in ./highlight.ts so this stays client-island-safe (no
+// Shiki/WASM in the bundle). See that file for why.
+export function CodeBlock({
+  html,
+  filename,
+  className,
+}: {
+  html: string;
+  filename?: string;
+  className?: string;
+}) {
+  return (
+    <div className="bg-text-dark rounded-2xl shadow-clay-dark overflow-hidden">
+      {filename && (
+        <div className="flex items-center gap-2 px-4 py-2.5 border-b border-white/10">
+          <div className="w-2.5 h-2.5 rounded-full bg-red-400/60" />
+          <div className="w-2.5 h-2.5 rounded-full bg-yellow-400/60" />
+          <div className="w-2.5 h-2.5 rounded-full bg-green-400/60" />
+          <span className="ml-2 text-xs text-white/30 font-mono">{filename}</span>
+        </div>
+      )}
+      <pre
+        className={`font-mono text-xs leading-relaxed p-5 m-0 overflow-x-auto ${className ?? ""}`}
+        dangerouslySetInnerHTML={{ __html: html }}
+      />
+    </div>
+  );
+}

package/src/ui/components/combobox.tsx

@@ -0,0 +1,119 @@
+import {
+  Combobox as ComboboxPrimitive,
+  type ComboboxInputValueChangeDetails,
+  type ComboboxValueChangeDetails,
+  useListCollection,
+} from "@ark-ui/react/combobox";
+import { useFilter } from "@ark-ui/react/locale";
+import { useEffect } from "preact/hooks";
+
+import { cn } from "../utils.ts";
+import { CheckIcon, MagnifyingGlassIcon } from "./icons.tsx";
+
+// One selectable option. `label` is what shows + what typing filters against;
+// `value` is what `onValueChange` reports.
+interface ComboboxOption {
+  value: string;
+  label: string;
+}
+
+interface ComboboxProps {
+  items: ComboboxOption[];
+  value?: string;
+  onValueChange?: (value: string) => void;
+  placeholder?: string;
+  emptyText?: string;
+  disabled?: boolean;
+  className?: string;
+}
+
+// A searchable single-select on Ark UI's Combobox. Ark drives filtering through
+// a collection, so this owns an input-value filter and re-renders the list from
+// it. Self-contained: pass `items` and it renders the search input, the filtered
+// list, and a check on the selected row.
+export function Combobox({
+  items,
+  value,
+  onValueChange,
+  placeholder = "Search…",
+  emptyText = "No results.",
+  disabled,
+  className,
+}: ComboboxProps) {
+  const { contains } = useFilter({ sensitivity: "base" });
+  const { collection, filter, set } = useListCollection({
+    initialItems: items,
+    filter: contains,
+    itemToValue: (item) => item.value,
+    itemToString: (item) => item.label,
+  });
+
+  // `useListCollection` seeds `initialItems` once; reseed when the item set changes
+  // (an async loader can deliver a different list after mount). Key on the values so
+  // this fires on real changes, not on every render — the parent passes a fresh array
+  // each time, so depending on the array reference would loop.
+  const itemsKey = items.map((item) => item.value).join(" ");
+  useEffect(() => {
+    set(items);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [itemsKey]);
+
+  return (
+    <ComboboxPrimitive.Root
+      data-slot="combobox"
+      collection={collection}
+      value={value ? [value] : []}
+      onValueChange={(details: ComboboxValueChangeDetails) =>
+        onValueChange?.(details.value[0] ?? "")
+      }
+      onInputValueChange={(details: ComboboxInputValueChangeDetails) => filter(details.inputValue)}
+      disabled={disabled}
+      openOnClick
+      className={cn("relative w-full", className)}
+    >
+      <ComboboxPrimitive.Control className="relative">
+        <MagnifyingGlassIcon className="pointer-events-none absolute left-2.5 top-1/2 size-4 -translate-y-1/2 opacity-50" />
+        <ComboboxPrimitive.Input
+          data-slot="combobox-input"
+          placeholder={placeholder}
+          className={cn(
+            "h-9 w-full rounded-md border border-input bg-background pl-8 pr-3 text-sm shadow-sm outline-none",
+            "placeholder:text-muted-foreground focus-visible:ring-1 focus-visible:ring-ring",
+            "disabled:cursor-not-allowed disabled:opacity-50",
+          )}
+        />
+      </ComboboxPrimitive.Control>
+      <ComboboxPrimitive.Positioner className="z-50">
+        <ComboboxPrimitive.Content
+          data-slot="combobox-content"
+          className={cn(
+            "z-50 max-h-72 w-[var(--reference-width)] overflow-x-hidden overflow-y-auto rounded-xl border border-border bg-popover p-1.5 text-popover-foreground shadow-md outline-none",
+            "data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95",
+            "data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95",
+          )}
+        >
+          {collection.items.map((item) => (
+            <ComboboxPrimitive.Item
+              key={item.value}
+              item={item}
+              data-slot="combobox-item"
+              className={cn(
+                "relative flex cursor-pointer select-none items-center gap-2 rounded-lg px-3 py-2 text-sm outline-none",
+                "data-[highlighted]:bg-accent data-[highlighted]:text-accent-foreground",
+                "data-[disabled]:pointer-events-none data-[disabled]:opacity-50",
+              )}
+            >
+              <ComboboxPrimitive.ItemText>{item.label}</ComboboxPrimitive.ItemText>
+              <ComboboxPrimitive.ItemIndicator className="ml-auto">
+                <CheckIcon className="size-4" />
+              </ComboboxPrimitive.ItemIndicator>
+            </ComboboxPrimitive.Item>
+          ))}
+          {collection.items.length === 0 && (
+            <div class="py-6 text-center text-sm text-muted-foreground">{emptyText}</div>
+          )}
+        </ComboboxPrimitive.Content>
+      </ComboboxPrimitive.Positioner>
+    </ComboboxPrimitive.Root>
+  );
+}

package/src/ui/components/config-field.tsx

@@ -0,0 +1,284 @@
+import type { ComponentChildren } from "preact";
+import { useState } from "preact/hooks";
+import { EyeIcon, EyeSlashIcon, FadersIcon, LockIcon, ListChecksIcon } from "./icons.tsx";
+import { Input } from "./input.tsx";
+import { Switch } from "./switch.tsx";
+
+export type ConfigFieldKind = "text" | "secret" | "number" | "boolean" | "enum";
+
+const ICONS: Record<ConfigFieldKind, ComponentChildren> = {
+  secret: <LockIcon className="w-[22px] h-[22px]" />,
+  enum: <ListChecksIcon className="w-[22px] h-[22px]" />,
+  text: <FadersIcon className="w-[22px] h-[22px]" />,
+  number: <FadersIcon className="w-[22px] h-[22px]" />,
+  boolean: <FadersIcon className="w-[22px] h-[22px]" />,
+};
+
+interface ConfigFieldProps {
+  kind: ConfigFieldKind;
+  label: string;
+  description?: string;
+  placeholder?: string;
+  /** Omit to hide the required/optional badge. */
+  required?: boolean;
+  /** Choices for `kind="enum"`. */
+  values?: string[];
+  /** Bounds for `kind="number"`, forwarded to the `<input>`. */
+  min?: number;
+  max?: number;
+  step?: number;
+  /** Controlled value. Pair with `onChange`. */
+  value?: string | number | boolean;
+  onChange?: (value: unknown) => void;
+  /** Uncontrolled seed (also drives the input's initial state). */
+  defaultValue?: string | number | boolean;
+  disabled?: boolean;
+  /**
+   * For `kind="secret"`: render the secret's display mask as the placeholder
+   * and a "leave blank to keep current value" hint instead of the regular
+   * placeholder.
+   */
+  redacted?: boolean;
+  /**
+   * For a redacted secret: the non-reversible display mask (e.g.
+   * `pk_live_••••`) computed at wrap time. Shown as the placeholder so the
+   * operator can tell which key is set; never the input's value, so it can't
+   * be submitted.
+   */
+  secretMask?: string;
+  id?: string;
+  /**
+   * Forwarded to the underlying `<input>`. Useful for docs-style previews
+   * that want to suppress browser form restoration / autofill so a prefill
+   * value isn't replaced by the user's last typed value on reload.
+   */
+  autoComplete?: string;
+}
+
+function ConfigField({
+  kind,
+  label,
+  description,
+  placeholder,
+  required,
+  values,
+  min,
+  max,
+  step,
+  value,
+  onChange,
+  defaultValue,
+  disabled,
+  redacted,
+  secretMask,
+  id: idProp,
+  autoComplete,
+}: ConfigFieldProps) {
+  const id = idProp ?? `cfg-${label.replace(/[^a-z0-9]+/gi, "-").toLowerCase()}`;
+
+  const [internal, setInternal] = useState<unknown>(defaultValue);
+  // Controlled mode is determined by the caller passing `onChange`. A
+  // controlled component can legitimately have `value === undefined`
+  // (a required-no-prefill input the user hasn't filled in yet), so gating
+  // on `value !== undefined` would silently flip into uncontrolled mode and
+  // drop every keystroke into local state instead of the parent's signal.
+  const isControlled = onChange !== undefined;
+  const effective = isControlled ? value : internal;
+  const emit = (v: unknown) => {
+    if (isControlled) onChange(v);
+    else setInternal(v);
+  };
+
+  return (
+    <div className="bg-card rounded-2xl shadow p-3.5 px-4 flex items-start gap-3">
+      <span className="text-trust">{ICONS[kind]}</span>
+      <div className="flex-1 min-w-0">
+        <div className="flex items-center gap-2">
+          <label htmlFor={id} className="text-sm font-bold text-foreground cursor-pointer">
+            {label}
+          </label>
+          {required !== undefined && (
+            <span className="text-[10px] font-bold px-[7px] py-0.5 rounded uppercase tracking-wide text-muted-foreground bg-surface-light">
+              {required ? "required" : "optional"}
+            </span>
+          )}
+        </div>
+        {description && (
+          <p className="text-xs mt-1 leading-snug text-muted-foreground">{description}</p>
+        )}
+        {kind !== "boolean" && (
+          <div className="mt-2">
+            <ConfigFieldInput
+              id={id}
+              kind={kind}
+              label={label}
+              placeholder={placeholder}
+              values={values}
+              min={min}
+              max={max}
+              step={step}
+              value={effective}
+              onChange={emit}
+              disabled={disabled === true}
+              redacted={redacted === true}
+              secretMask={secretMask}
+              autoComplete={autoComplete}
+            />
+          </div>
+        )}
+        {redacted && (
+          <p className="text-xs text-muted-foreground leading-snug italic mt-1.5">
+            Leave blank to keep current value.
+          </p>
+        )}
+      </div>
+      {kind === "boolean" && (
+        <Switch
+          id={id}
+          checked={effective === true}
+          onCheckedChange={(d: { checked: boolean }) => emit(d.checked === true)}
+          disabled={disabled === true}
+          label={label}
+          labelClassName="sr-only"
+        />
+      )}
+    </div>
+  );
+}
+
+interface ConfigFieldInputProps {
+  id: string;
+  /** A boolean renders as a Switch beside the card, not as an input. */
+  kind: Exclude<ConfigFieldKind, "boolean">;
+  /** Only for the secret reveal button's aria-label — the visible label is the
+   * `<label htmlFor>` above, and several secrets on one form would otherwise
+   * all announce as an identical "Show value". */
+  label: string;
+  placeholder?: string;
+  values?: string[];
+  min?: number;
+  max?: number;
+  step?: number;
+  value: unknown;
+  onChange: (value: unknown) => void;
+  disabled: boolean;
+  redacted: boolean;
+  secretMask?: string;
+  autoComplete?: string;
+}
+
+function ConfigFieldInput({
+  id,
+  kind,
+  label,
+  placeholder,
+  values,
+  min,
+  max,
+  step,
+  value,
+  onChange,
+  disabled,
+  redacted,
+  secretMask,
+  autoComplete,
+}: ConfigFieldInputProps) {
+  // Reveal state for `kind="secret"`. Declared unconditionally (hooks can't
+  // sit behind the kind branches below) and per-field, so revealing one
+  // secret never unmasks its neighbours.
+  const [revealed, setRevealed] = useState(false);
+
+  if (kind === "enum") {
+    return (
+      <select
+        id={id}
+        className="h-8 w-full rounded-2xl border border-border bg-secondary px-2.5 text-sm shadow-sm outline-none focus-visible:ring-3 focus-visible:ring-ring/50 disabled:opacity-50"
+        value={typeof value === "string" ? value : ""}
+        disabled={disabled}
+        onChange={(e) => onChange((e.target as HTMLSelectElement).value)}
+      >
+        <option value="" disabled>
+          Select…
+        </option>
+        {(values ?? []).map((v) => (
+          <option key={v} value={v}>
+            {v}
+          </option>
+        ))}
+      </select>
+    );
+  }
+
+  if (kind === "number") {
+    return (
+      <Input
+        id={id}
+        type="number"
+        value={typeof value === "number" ? String(value) : ((value as string) ?? "")}
+        placeholder={placeholder}
+        min={min}
+        max={max}
+        step={step}
+        disabled={disabled}
+        autoComplete={autoComplete}
+        onInput={(e) => {
+          const raw = (e.target as HTMLInputElement).value;
+          onChange(raw === "" ? undefined : Number(raw));
+        }}
+      />
+    );
+  }
+
+  if (kind === "secret") {
+    return (
+      <div className="relative">
+        <Input
+          id={id}
+          type={revealed ? "text" : "password"}
+          autoComplete={autoComplete ?? "new-password"}
+          value={typeof value === "string" ? value : ""}
+          placeholder={redacted ? secretMask : placeholder}
+          disabled={disabled}
+          // Room for the reveal button, which overlays the input's right edge.
+          className="pr-9"
+          onInput={(e) => onChange((e.target as HTMLInputElement).value)}
+        />
+        {/* An API key typed blind is a support ticket: the operator pastes or
+            types it once, cannot proof-read it, and the app fails to
+            authenticate with no way to tell a typo from a wrong key. Masking
+            by default still matters (screen shares, over-the-shoulder), so
+            this is opt-in per field rather than a global preference.
+            `type="button"` is load-bearing — this sits inside the install and
+            edit forms, and the default `submit` would deploy the app. */}
+        <button
+          type="button"
+          onClick={() => setRevealed(!revealed)}
+          disabled={disabled}
+          aria-label={`${revealed ? "Hide" : "Show"} ${label}`}
+          aria-pressed={revealed}
+          className="absolute right-0 top-0 h-8 w-9 grid place-items-center rounded-r-2xl text-muted-foreground hover:text-foreground disabled:pointer-events-none disabled:opacity-50 cursor-pointer"
+        >
+          {revealed ? (
+            <EyeSlashIcon className="w-[18px] h-[18px]" />
+          ) : (
+            <EyeIcon className="w-[18px] h-[18px]" />
+          )}
+        </button>
+      </div>
+    );
+  }
+
+  return (
+    <Input
+      id={id}
+      type="text"
+      value={typeof value === "string" ? value : ""}
+      placeholder={placeholder}
+      disabled={disabled}
+      autoComplete={autoComplete}
+      onInput={(e) => onChange((e.target as HTMLInputElement).value)}
+    />
+  );
+}
+
+export { ConfigField };