@vespercms/admin 0.0.0-stage → 0.1.0-next.1

package/src/studio.css

@@ -0,0 +1,168 @@
+/*
+ * The studio's stylesheet: Tailwind plus Vesper's token budget. It is compiled
+ * when @vespercms/admin is published (dist/studio.css), so sites need no
+ * Tailwind of their own. In this workspace the source is used directly.
+ */
+@import 'tailwindcss' source(none);
+@import '@vespercms/ui/tokens.css';
+
+@source '../../ui/src';
+@source '.';
+
+/*
+ * Figtree, self-hosted (DECISIONS.md, "The studio self-hosts Figtree"): two
+ * weights, latin only. The published build inlines both files into
+ * dist/studio.css, so /admin never asks Google or a CDN for anything.
+ * Characters outside the range fall back to the system stack.
+ */
+@font-face {
+  font-family: Figtree;
+  font-style: normal;
+  font-weight: 400;
+  font-display: swap;
+  src: url('@fontsource/figtree/files/figtree-latin-400-normal.woff2') format('woff2');
+  unicode-range:
+    U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329,
+    U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
+}
+
+@font-face {
+  font-family: Figtree;
+  font-style: normal;
+  font-weight: 600;
+  font-display: swap;
+  src: url('@fontsource/figtree/files/figtree-latin-600-normal.woff2') format('woff2');
+  unicode-range:
+    U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329,
+    U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
+}
+
+@layer base {
+  /* The studio fills the page and never inherits the site's own styles. */
+  #vesper-studio {
+    min-height: 100vh;
+  }
+
+  h1,
+  h2,
+  h3 {
+    font-weight: var(--font-weight-semibold);
+  }
+}
+
+@layer components {
+  /* The geo field's map pin: a real button, so it has a visible focus ring. */
+  .vesper-map-pin {
+    width: 1.5rem;
+    height: 1.5rem;
+    border-radius: 9999px 9999px 9999px 0;
+    transform: rotate(-45deg);
+    background-color: var(--color-accent);
+    border: 2px solid var(--color-on-accent);
+    box-shadow: var(--shadow-overlay);
+    cursor: grab;
+  }
+
+  .vesper-map-pin:focus-visible {
+    outline: 3px solid var(--color-focus);
+    outline-offset: 3px;
+  }
+
+  /* An empty date field shows no date until it's used: Safari's is today's (widgets/blank-date.ts). */
+  input[data-blank]::-webkit-datetime-edit {
+    opacity: 0;
+  }
+}
+
+@layer components {
+  /* The body's writing view: hierarchy from size and weight, not boxes (spec §10.2). */
+  .vesper-body > * + * {
+    margin-top: 0.75em;
+  }
+
+  .vesper-body h1 {
+    font-size: 1.5rem;
+    font-weight: var(--font-weight-semibold);
+  }
+
+  .vesper-body h2 {
+    font-size: 1.25rem;
+    font-weight: var(--font-weight-semibold);
+  }
+
+  /* Each level a step smaller, down to the text's own size; the last is muted to tell it apart. */
+  .vesper-body h3,
+  .vesper-body h4,
+  .vesper-body h5,
+  .vesper-body h6 {
+    font-size: 1.0625rem;
+    font-weight: var(--font-weight-semibold);
+  }
+
+  .vesper-body h4 {
+    font-size: 1rem;
+  }
+
+  .vesper-body h5,
+  .vesper-body h6 {
+    font-size: 0.9375rem;
+  }
+
+  .vesper-body h6 {
+    color: var(--color-content-muted);
+  }
+
+  .vesper-body ul {
+    list-style: disc;
+    padding-left: 1.5em;
+  }
+
+  .vesper-body ol {
+    list-style: decimal;
+    padding-left: 1.5em;
+  }
+
+  .vesper-body blockquote {
+    border-left: 1px solid var(--color-border-strong);
+    padding-left: 1em;
+    color: var(--color-content-muted);
+  }
+
+  .vesper-body code {
+    font-family: var(--font-mono);
+    font-size: 0.9em;
+  }
+
+  .vesper-body pre {
+    font-family: var(--font-mono);
+    font-size: 0.875rem;
+    background-color: var(--color-surface);
+    border: 1px solid var(--color-border);
+    border-radius: 0.375rem;
+    padding: 0.75em;
+    overflow-x: auto;
+  }
+
+  .vesper-body a {
+    color: var(--color-accent);
+    text-decoration: underline;
+    text-underline-offset: 2px;
+  }
+
+  .vesper-body img {
+    display: inline-block;
+    max-height: 12rem;
+    border-radius: 0.25rem;
+  }
+
+  .vesper-body hr {
+    border: 0;
+    border-top: 1px solid var(--color-border);
+  }
+
+  /* Only while the text has focus, as for the blocks' own outlines (views.tsx). */
+  .vesper-body.ProseMirror-focused .ProseMirror-selectednode {
+    outline: 2px solid var(--color-focus);
+    outline-offset: 2px;
+  }
+}

package/src/types.ts

@@ -0,0 +1,82 @@
+import type { Manifest, UrlEntry, WidgetProps } from '@vespercms/core';
+import type { CloudConnection } from './cloud/connection.ts';
+import type { CloudSettings } from './cloud/session.ts';
+import type { GitHubStudioSettings } from './github/session.ts';
+import type { ComponentType } from 'react';
+import type { StudioApi } from './app/api.ts';
+
+/** What a widget receives (spec §6.3.3); defined in core so sites can type widgets without the studio. */
+export type { WidgetProps };
+
+// Widgets are registered by name and receive values of many shapes, so the
+// registry's component type can't be narrower than this.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type WidgetComponent = ComponentType<WidgetProps<any>>;
+
+/** A custom widget from vesper.config.ts, loaded only when a field uses it. */
+export type WidgetLoader = () => Promise<{ default: WidgetComponent }>;
+
+export type StudioOptions = {
+  manifest: Manifest;
+  /**
+   * The storage back end, or `null` when this build has none yet: a deployed
+   * site before GitHub mode (Phase 3). The studio then explains where to edit.
+   */
+  api: StudioApi | null;
+  /** Custom widgets by name (spec §6.3.3). */
+  widgets?: Record<string, WidgetLoader>;
+  /**
+   * Loads declared MDX components' Zod props schemas from vesper.config.ts,
+   * so props are checked exactly as the site checks them (spec §6.5.2). On
+   * first use: Zod stays out of the studio's first load.
+   */
+  loadMdxProps?: () => Promise<Record<string, unknown>>;
+  /** Shown in the top bar and the page title. */
+  siteName?: string;
+  /** The site's home page, for "View site". */
+  siteUrl?: string;
+  /**
+   * GitHub mode in a built site (spec §6.8): with no `api`, the studio
+   * signs the editor in with GitHub and saves to this repository.
+   */
+  github?: GitHubStudioSettings | null;
+  /** The site's static routes at build, for GitHub mode's collision checks. */
+  routes?: readonly (readonly [string, string])[];
+  /** Function-form URL patterns from vesper.config.ts, for GitHub mode's moves and links. */
+  loadUrlFunctions?: () => Promise<Readonly<Record<string, (entry: UrlEntry) => unknown>>>;
+  /** Who is signed in, set by GitHub mode and the cloud. */
+  account?: Account;
+  /**
+   * The cloud in a built site (spec §6.9): with no `api`, the studio signs
+   * the editor in to Vesper, and saves become drafts.
+   */
+  cloud?: CloudSettings | null;
+  /** The studio connected to the cloud, set by the cloud's gate once signed in. */
+  connection?: CloudConnection;
+};
+
+/** The signed-in editor, in GitHub mode or the cloud: the user menu shows it. */
+export type Account = {
+  /** The user menu's button: `@login` on GitHub, the person's name on Vesper. */
+  label: string;
+  /** The person's name, at the top of the open menu and for their initials. */
+  name: string;
+  /** Their picture's address, beside the name; without one, their initials show. */
+  picture?: string;
+  /** The menu's name: "Signed in to GitHub as @login". */
+  description: string;
+  /** The menu's way out: "Sign out of GitHub", "Sign out of Vesper". */
+  signOutLabel: string;
+  /** The cloud's dashboard, for "Open dashboard". */
+  dashboardUrl?: string;
+  /**
+   * GitHub mode: the repository is public, so a change scheduled there can
+   * be read before it goes live (spec §6.17). The Schedule dialog says so.
+   */
+  publicRepository?: boolean;
+  signOut: () => void;
+  /** Signs in again after the session expired, coming back to the same screen. */
+  signInAgain: () => void;
+  /** True once GitHub has said the session expired. */
+  expired: boolean;
+};

package/src/widgets/basic.tsx

@@ -0,0 +1,315 @@
+import {
+  formatYamlSnippet,
+  parseYamlSnippet,
+  type DataValue,
+  type FieldModel,
+  type FieldOption,
+} from '@vespercms/core';
+import { MultiCombobox, RadioGroup, Select, Switch, cx } from '@vespercms/ui';
+import { useState } from 'react';
+import type { WidgetProps } from '../types.ts';
+import { useBlankWhenEmpty } from './blank-date.ts';
+
+/*
+ * The simple built-in widgets (spec §6.3.2). Each follows the custom widget
+ * contract: the control takes `id`, `aria-describedby` and `aria-invalid`,
+ * and the editor renders the label. None of them validate.
+ */
+
+/** Native inputs share the ui kit's control look. */
+export const inputClass = cx(
+  'min-h-10 w-full rounded-md border border-border-strong bg-surface-sunken px-3 py-2 text-body text-content',
+  'outline-none focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-2 focus-visible:outline-focus',
+  'focus-visible:ring-6 focus-visible:ring-(color:--glow-focus)',
+  'aria-[invalid=true]:border-danger disabled:opacity-60',
+);
+
+/** Clearing an optional field removes its key; a required one keeps `''` so the schema can say why. */
+function emptyAs(field: FieldModel): '' | undefined {
+  return field.required ? '' : undefined;
+}
+
+function textProps(props: WidgetProps<string>) {
+  const { onChange, field, id, describedBy, invalid, disabled } = props;
+  // A file can hold a number where the schema expects text; show it rather than hide it.
+  const value: unknown = props.value;
+  return {
+    id,
+    value:
+      typeof value === 'string'
+        ? value
+        : typeof value === 'number' || typeof value === 'boolean'
+          ? String(value)
+          : '',
+    onChange: (event: { target: { value: string } }) => {
+      onChange(event.target.value === '' ? emptyAs(field) : event.target.value);
+    },
+    'aria-describedby': describedBy,
+    'aria-invalid': invalid || undefined,
+    'aria-required': field.required || undefined,
+    disabled,
+    placeholder: field.placeholder,
+    autoComplete: field.autocomplete,
+    className: inputClass,
+  };
+}
+
+export function TextWidget(props: WidgetProps<string>) {
+  return <input type="text" {...textProps(props)} />;
+}
+
+export function EmailWidget(props: WidgetProps<string>) {
+  const input = textProps(props);
+  return (
+    <input type="email" inputMode="email" {...input} autoComplete={input.autoComplete ?? 'email'} />
+  );
+}
+
+export function TextAreaWidget(props: WidgetProps<string>) {
+  const rows = props.field.widget === 'markdown' ? 8 : 3;
+  return <textarea rows={rows} {...textProps(props)} className={cx(inputClass, 'resize-y')} />;
+}
+
+export function NumberWidget({
+  value,
+  onChange,
+  field,
+  id,
+  describedBy,
+  invalid,
+  disabled,
+}: WidgetProps<number>) {
+  // The text is kept separately so "1." or "-" can be typed on the way to a number.
+  const [text, setText] = useState(value === undefined ? '' : String(value));
+  const c = field.constraints;
+  return (
+    <input
+      id={id}
+      type="number"
+      inputMode={c?.integer ? 'numeric' : 'decimal'}
+      value={text}
+      min={c?.min}
+      max={c?.max}
+      step={c?.step ?? (c?.integer ? 1 : 'any')}
+      onChange={(event) => {
+        setText(event.target.value);
+        if (event.target.value === '') onChange(undefined);
+        else if (Number.isFinite(event.target.valueAsNumber)) onChange(event.target.valueAsNumber);
+      }}
+      aria-describedby={describedBy}
+      aria-invalid={invalid || undefined}
+      aria-required={field.required || undefined}
+      disabled={disabled}
+      className={cx(inputClass, 'max-w-48')}
+    />
+  );
+}
+
+export function SwitchWidget({
+  value,
+  onChange,
+  id,
+  describedBy,
+  invalid,
+  disabled,
+}: WidgetProps<boolean>) {
+  return (
+    <Switch
+      id={id}
+      isSelected={value === true}
+      onChange={onChange}
+      isDisabled={disabled}
+      isInvalid={invalid}
+      aria-labelledby={`${id}-label`}
+      aria-describedby={describedBy}
+    >
+      {null}
+    </Switch>
+  );
+}
+
+/** YYYY-MM-DD of a date as stored: date-only values are midnight UTC (YAML timestamps). */
+function dateText(value: DataValue): string {
+  if (value instanceof Date && !Number.isNaN(value.getTime()))
+    return value.toISOString().slice(0, 10);
+  if (typeof value === 'string') return value.slice(0, 10);
+  return '';
+}
+
+/**
+ * A calendar date. The value keeps its type: a Date stays a Date (written
+ * back as `2026-10-17`), and a quoted string stays a string.
+ */
+export function DateWidget({
+  value,
+  onChange,
+  field,
+  id,
+  describedBy,
+  invalid,
+  disabled,
+}: WidgetProps<Date | string>) {
+  const text = dateText(value);
+  const blank = useBlankWhenEmpty(text);
+  return (
+    <input
+      id={id}
+      type="date"
+      value={text}
+      {...blank}
+      onChange={(event) => {
+        const text = event.target.value;
+        if (text === '')
+          onChange(emptyAs(field) === '' && typeof value === 'string' ? '' : undefined);
+        else onChange(typeof value === 'string' ? text : new Date(`${text}T00:00:00.000Z`));
+      }}
+      aria-describedby={describedBy}
+      aria-invalid={invalid || undefined}
+      aria-required={field.required || undefined}
+      disabled={disabled}
+      className={cx(inputClass, 'max-w-56')}
+    />
+  );
+}
+
+function optionsOf(field: FieldModel): FieldOption[] {
+  return field.constraints?.options ?? field.children?.[0]?.constraints?.options ?? [];
+}
+
+export function SelectWidget({
+  value,
+  onChange,
+  field,
+  id,
+  describedBy,
+  invalid,
+  disabled,
+}: WidgetProps<string>) {
+  return (
+    <Select
+      id={id}
+      aria-labelledby={`${id}-label`}
+      aria-describedby={describedBy}
+      options={optionsOf(field)}
+      value={value ?? null}
+      onChange={(next) => {
+        onChange(next ?? undefined);
+      }}
+      isInvalid={invalid}
+      isDisabled={disabled}
+    />
+  );
+}
+
+/** Up to four options, all visible. Rendered inside the field's fieldset, which names it. */
+export function RadioWidget({
+  value,
+  onChange,
+  field,
+  id,
+  describedBy,
+  invalid,
+  disabled,
+}: WidgetProps<string>) {
+  return (
+    <RadioGroup
+      id={id}
+      aria-labelledby={`${id}-label`}
+      aria-describedby={describedBy}
+      options={optionsOf(field)}
+      value={value ?? null}
+      onChange={onChange}
+      isInvalid={invalid}
+      isDisabled={disabled}
+      orientation={optionsOf(field).length <= 3 ? 'horizontal' : 'vertical'}
+    />
+  );
+}
+
+/** A list of strings: type and press Enter to add, each with a named remove button. */
+export function TagsWidget({
+  value,
+  onChange,
+  field,
+  id,
+  describedBy,
+  invalid,
+  disabled,
+}: WidgetProps<string[]>) {
+  const values = Array.isArray(value) ? value.filter((v) => typeof v === 'string') : [];
+  const options = optionsOf(field);
+  const multiple = field.children?.[0]?.kind === 'enum';
+  return (
+    <MultiCombobox
+      id={id}
+      aria-labelledby={`${id}-label`}
+      aria-describedby={describedBy}
+      options={multiple ? options : values.map((v) => ({ value: v, label: v }))}
+      values={values}
+      onChange={(next) => {
+        onChange(next.length === 0 && !field.required ? undefined : next);
+      }}
+      allowsCustomValue={!multiple}
+      itemName={multiple ? 'option' : 'tag'}
+      isInvalid={invalid}
+      isDisabled={disabled}
+    />
+  );
+}
+
+/**
+ * The raw field (spec §6.3 step 4): any value Vesper can't map to a control,
+ * edited as a small YAML snippet and parsed the way Astro parses it. The
+ * text is kept while it's invalid, so nothing typed is lost.
+ */
+export function RawWidget({
+  value,
+  onChange,
+  field,
+  id,
+  describedBy,
+  invalid,
+  disabled,
+}: WidgetProps<DataValue>) {
+  const [text, setText] = useState(() => formatYamlSnippet(value));
+  const [problem, setProblem] = useState<string | null>(null);
+  const problemId = `${id}-yaml`;
+  return (
+    <>
+      <textarea
+        id={id}
+        rows={Math.min(12, Math.max(3, text.split('\n').length + 1))}
+        value={text}
+        spellCheck={false}
+        onChange={(event) => {
+          setText(event.target.value);
+          const parsed = parseYamlSnippet(event.target.value);
+          if (parsed.ok) {
+            setProblem(null);
+            onChange(parsed.value);
+          } else {
+            setProblem(parsed.message);
+          }
+        }}
+        aria-describedby={[describedBy, `${id}-raw`, problem ? problemId : undefined]
+          .filter(Boolean)
+          .join(' ')}
+        aria-invalid={invalid || problem !== null || undefined}
+        aria-required={field.required || undefined}
+        disabled={disabled}
+        className={cx(inputClass, 'resize-y font-mono text-small')}
+      />
+      <p id={`${id}-raw`} className="text-small text-content-muted">
+        Edited as YAML
+        {field.unknownReason
+          ? `: Vesper has no control for this ${field.unknownReason} field.`
+          : '.'}
+      </p>
+      {problem && (
+        <p id={problemId} className="text-small text-danger">
+          {problem}
+        </p>
+      )}
+    </>
+  );
+}

package/src/widgets/blank-date.ts

@@ -0,0 +1,32 @@
+import { useState, type FocusEvent, type KeyboardEvent } from 'react';
+
+/*
+ * Safari draws today's date and time, greyed, in an empty date field, and
+ * editors took it for a time already chosen: "Comes down" looked set when it
+ * wasn't (WebKit bug 233215). An empty field is drawn blank until it's
+ * clicked or typed in, and blank again when it's left with nothing in it (studio.css
+ * hides `::-webkit-datetime-edit` under `data-blank`). Chrome's
+ * "mm/dd/yyyy" goes with it; the label says what goes there, and Firefox,
+ * which draws neither, is unchanged.
+ */
+
+/** Keys that pass through or leave a field without starting to fill it in. */
+const PASSING = new Set(['Tab', 'Shift', 'Escape', 'Enter', 'Meta', 'Control', 'Alt']);
+
+/** Props for a `date` or `datetime-local` input whose value is `value`. */
+export function useBlankWhenEmpty(value: string) {
+  const [engaged, setEngaged] = useState(false);
+  return {
+    'data-blank': value === '' && !engaged ? '' : undefined,
+    onPointerDown: () => {
+      setEngaged(true);
+    },
+    onKeyDown: (event: KeyboardEvent) => {
+      if (!PASSING.has(event.key)) setEngaged(true);
+    },
+    // A date typed partway has no value yet, but its parts must stay in sight.
+    onBlur: (event: FocusEvent<HTMLInputElement>) => {
+      if (!event.currentTarget.validity.badInput) setEngaged(false);
+    },
+  };
+}