@diagonal-hq/cli 0.0.0-stage → 0.1.0

package/dist/globals.d.ts

@@ -0,0 +1,72 @@
+// The `Sdk` and `React` globals of page, layout, component, and email files.
+// The same types that the deploy type check uses.
+/// <reference path="./sdk-contract.d.ts" />
+declare namespace React {
+  type ReactNode = RenderableChild;
+  type ReactElement = any;
+  type ComponentType<P = any> = (props: P) => any;
+  type FC<P = any> = (props: P & { children?: RenderableChild }) => any;
+  type PropsWithChildren<P = unknown> = P & { children?: RenderableChild };
+  type CSSProperties = { [property: string]: any };
+  type RefObject<T = any> = { current: T };
+  type MutableRefObject<T = any> = { current: T };
+  type Ref<T = any> = ((instance: T | null) => void) | RefObject<T | null> | null;
+  type Dispatch<A = any> = (value: A) => void;
+  type SetStateAction<S = any> = S | ((previousState: S) => S);
+  type DependencyList = readonly unknown[];
+  type ChangeEvent<T = any> = any;
+  type FormEvent<T = any> = any;
+  type MouseEvent<T = any> = any;
+  type KeyboardEvent<T = any> = any;
+  type FocusEvent<T = any> = any;
+}
+interface DiagonalReactGlobal {
+  useState(initialState: null): [any, React.Dispatch<React.SetStateAction<any>>];
+  useState(initialState: never[]): [any[], React.Dispatch<React.SetStateAction<any[]>>];
+  useState<S>(initialState: S | (() => S)): [S, React.Dispatch<React.SetStateAction<S>>];
+  useState<S = undefined>(): [S | undefined, React.Dispatch<React.SetStateAction<S | undefined>>];
+  useEffect(effect: () => any, deps?: React.DependencyList): void;
+  useLayoutEffect(effect: () => any, deps?: React.DependencyList): void;
+  useMemo<T>(factory: () => T, deps?: React.DependencyList): T;
+  useCallback<T extends (...args: any[]) => any>(callback: T, deps?: React.DependencyList): T;
+  useRef<T>(initialValue: T): React.RefObject<T>;
+  useRef<T>(initialValue: T | null): React.RefObject<T | null>;
+  useRef<T>(initialValue: T | undefined): React.RefObject<T | undefined>;
+  useReducer<S, A>(reducer: (state: S, action: A) => S, initialState: S): [S, React.Dispatch<A>];
+  useReducer<S, A, I>(
+    reducer: (state: S, action: A) => S,
+    initializerArg: I,
+    initializer: (arg: I) => S
+  ): [S, React.Dispatch<A>];
+  useContext<T = any>(context: unknown): T;
+  useId(): string;
+  useTransition(): [boolean, (callback: () => void) => void];
+  useDeferredValue<T>(value: T): T;
+  memo<T>(component: T, arePropsEqual?: (previous: any, next: any) => boolean): T;
+  forwardRef<T = any, P = any>(
+    render: (props: P, ref: React.Ref<T>) => any
+  ): (props: P & { ref?: React.Ref<T> }) => any;
+  [member: string]: any;
+}
+declare const React: DiagonalReactGlobal;
+declare namespace JSX {
+  type Element = any;
+  interface ElementChildrenAttribute { children: {}; }
+  interface IntrinsicAttributes { key?: any; }
+  interface IntrinsicElements { [name: string]: { [attribute: string]: any; children?: RenderableChild }; }
+}
+type RenderableChild =
+  | string
+  | number
+  | bigint
+  | boolean
+  | null
+  | undefined
+  | Iterable<RenderableChild>
+  | Promise<RenderableChild>;
+
+// The editor does not know the workspace components, so any Sdk.Custom name is allowed.
+declare module "diagonal:sdk-internal" {
+interface CustomComponentRegistry { [key: string]: SdkComponent }
+}
+

package/dist/index.d.ts

@@ -0,0 +1,274 @@
+import './globals';
+
+// The configuration helpers of file-based workspaces. The workspace build
+// reads these calls as static data. index.js implements each define* function
+// as an identity function and each field builder as `{ $field, ...options }`.
+
+export type StaticValue =
+  | string
+  | number
+  | boolean
+  | null
+  | readonly StaticValue[]
+  | { readonly [key: string]: StaticValue };
+
+export type ConfigDefinition = {
+  name: string;
+  brand?: { readonly [key: string]: StaticValue };
+  settings?: { readonly [key: string]: StaticValue };
+};
+
+export declare function defineConfig<const T extends ConfigDefinition>(config: T): T;
+
+export type FieldType =
+  | 'text'
+  | 'email'
+  | 'number'
+  | 'boolean'
+  | 'date'
+  | 'datetime'
+  | 'phone'
+  | 'url'
+  | 'select'
+  | 'money'
+  | 'markdown'
+  | 'relation';
+
+export type FieldOptions = {
+  label?: string;
+  description?: string | null;
+  required?: boolean;
+  unique?: boolean;
+  index?: boolean;
+  default?: StaticValue;
+  [setting: string]: StaticValue | undefined;
+};
+
+export type SelectOption = { label: string; value: string };
+
+export type SelectFieldOptions = FieldOptions & { options: readonly SelectOption[] };
+
+export type RelationType = 'belongs_to' | 'has_many' | 'belongs_to_many';
+
+export type RelationFieldOptions = FieldOptions & {
+  /** The id or slug of the related resource. */
+  resource: string;
+  type?: RelationType;
+};
+
+export type FieldDefinition<TType extends FieldType = FieldType> = {
+  readonly $field: TType;
+};
+
+export declare const field: {
+  text(options?: FieldOptions): FieldDefinition<'text'>;
+  /** Stored as a `text` field. */
+  longText(options?: FieldOptions): FieldDefinition<'text'>;
+  email(options?: FieldOptions): FieldDefinition<'email'>;
+  number(options?: FieldOptions): FieldDefinition<'number'>;
+  boolean(options?: FieldOptions): FieldDefinition<'boolean'>;
+  date(options?: FieldOptions): FieldDefinition<'date'>;
+  datetime(options?: FieldOptions): FieldDefinition<'datetime'>;
+  phone(options?: FieldOptions): FieldDefinition<'phone'>;
+  url(options?: FieldOptions): FieldDefinition<'url'>;
+  select(options: SelectFieldOptions): FieldDefinition<'select'>;
+  money(options?: FieldOptions): FieldDefinition<'money'>;
+  markdown(options?: FieldOptions): FieldDefinition<'markdown'>;
+  relation(options: RelationFieldOptions): FieldDefinition<'relation'>;
+};
+
+export type PolicyScope =
+  | 'index'
+  | 'show'
+  | 'count'
+  | 'aggregate'
+  | 'store'
+  | 'storeMany'
+  | 'update'
+  | 'destroy'
+  | 'restore'
+  | 'validate';
+
+export type PolicyAccess = 'public' | 'protected';
+
+export type PolicyDefinition = {
+  name: string;
+  scope: 'all' | readonly PolicyScope[];
+  access: PolicyAccess;
+  description?: string | null;
+};
+
+export type IndexDefinition<TKey extends string = string> = {
+  fields: readonly TKey[];
+  unique?: boolean;
+};
+
+export type ResourceDefinition<
+  TFields extends Record<string, FieldDefinition> = Record<string, FieldDefinition>
+> = {
+  /**
+   * A lowercase UUID v7, for example '0199f000-0000-7000-8000-000000000001'.
+   * `diagonal check` suggests a new one when the id is not v7. Keep it
+   * stable: records and workflows refer to it.
+   */
+  id: string;
+  slug: string;
+  name: string;
+  singularName: string;
+  displayField?: Extract<keyof TFields, string>;
+  fields: TFields;
+  indexes?: readonly IndexDefinition<Extract<keyof TFields, string>>[];
+  policies: readonly PolicyDefinition[];
+};
+
+export declare function defineResource<const TFields extends Record<string, FieldDefinition>>(
+  resource: ResourceDefinition<TFields>
+): ResourceDefinition<TFields>;
+
+/** A TipTap document whose mentions resolve against the page's bound records. */
+export type PageMetaResolver = { readonly type: string; readonly [key: string]: unknown };
+
+export type PageRouteParam = {
+  /** The slug or id of the resource whose record the parameter names. */
+  resource: string;
+  /** The field the parameter matches. Defaults to the record id. */
+  lookupField?: string | null;
+  /** Relation fields to load with the record. */
+  relations?: readonly string[];
+  scope?: 'active' | 'activeOrArchived' | 'archived' | null;
+};
+
+export type PageAuthorizer =
+  | null
+  | 'authenticated'
+  | {
+      /** The slug or id of the resource whose signed-in records may view the page. */
+      resource?: string | null;
+      /** Permission ids. A viewer needs any one of them. */
+      permissions?: readonly string[];
+    };
+
+export type PageDefinition = {
+  /** The URL pattern. Route parameters use `{name}`, for example `/members/{id}`. */
+  route: string;
+  /** The name in the admin. Defaults to the title. */
+  name?: string | null;
+  title?: string | PageMetaResolver | null;
+  description?: string | PageMetaResolver | null;
+  /** A public workspace file id, or a resolver that names one. */
+  ogImage?: string | PageMetaResolver | null;
+  /** HTML added to the page's `<head>`. */
+  headHtml?: string | null;
+  /** The file name of a layout in `layouts/`, without the extension. */
+  layout?: string | null;
+  /** `print` renders without a layout. */
+  renderProfile?: 'standard' | 'print';
+  /** Whether the sitemap lists the page. Defaults to true, or false for a print page. */
+  sitemap?: boolean;
+  /** The host of a connected custom domain. A page with a domain serves only there. */
+  domain?: string | null;
+  /** A paused page does not serve. */
+  paused?: boolean;
+  authorizer?: PageAuthorizer;
+  /** The record each route parameter binds to, keyed by parameter name. */
+  params?: Readonly<Record<string, PageRouteParam>>;
+};
+
+export type PageComponent = () => unknown;
+
+export declare function definePage<const T extends PageDefinition>(
+  page: T,
+  component: PageComponent
+): T;
+
+export type LayoutProps = { children?: React.ReactNode };
+
+export type EmailDefinition = { subject: string };
+
+export declare function defineEmail<const T extends EmailDefinition, P>(
+  email: T,
+  component: (props: P) => unknown
+): T;
+
+export type NavigationItem = { label: string; route: string; icon?: string | null };
+
+export type NavigationDefinition = { id: string; items: readonly NavigationItem[] };
+
+export declare function defineNavigation<const T extends NavigationDefinition>(navigation: T): T;
+
+/** The slug, name, or id of a resource. */
+export type ResourceReference = string;
+
+export type WorkflowRunAs =
+  | 'system'
+  /** Only for request workflows: the signed-in user who calls the route. */
+  | 'session'
+  | {
+      resource: ResourceReference;
+      /** The lowercase UUID of the identity record. */
+      record: string;
+    };
+
+export type RequestTrigger = {
+  type: 'request';
+  /** The route. Route parameters use `{name}`, for example `/api/members/{id}`. */
+  path: string;
+  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+};
+
+export type RecordEventTrigger = {
+  type: 'recordEvent';
+  resource: ResourceReference;
+  event: 'created' | 'updated' | 'deleted' | 'restored' | 'saved';
+  filters?: StaticValue;
+};
+
+export type RecordLifecycleTrigger = {
+  type: 'recordLifecycle';
+  resource: ResourceReference;
+  hook: 'creating' | 'updating' | 'saving' | 'deleting' | 'restoring';
+};
+
+export type RecordScheduleTrigger = {
+  type: 'recordSchedule';
+  resource: ResourceReference;
+  /** The key of a date or datetime field of the resource. */
+  dateField: string;
+  /** Signed ISO 8601 durations in days, hours, or minutes, for example `'-P1D'` or `'+PT2H'`. */
+  offsets: readonly string[];
+};
+
+export type ScheduledTrigger = {
+  type: 'scheduled';
+  /** A cron expression with 5 fields, for example `'0 2 * * *'`. */
+  expression: string;
+};
+
+export type WorkflowEventTrigger = {
+  type: 'workflowEvent';
+  /** The path of another workflow, for example `'workflows/welcome.ts'`. */
+  workflow: `workflows/${string}.ts`;
+  event: 'execution.success' | 'execution.error';
+};
+
+export type ManualTrigger = { type: 'manual' };
+
+type ConfigBase = { title: string; description?: string | null };
+
+/**
+ * The `export const config` of a `workflows/<name>.ts` file. The build reads it as static data and
+ * never runs it. A background trigger (recordEvent, recordSchedule, scheduled, workflowEvent)
+ * needs `runAs`. A request workflow runs as the caller (`'session'`) by default.
+ */
+export type WorkflowConfig =
+  | (ConfigBase & {
+      trigger: RequestTrigger;
+      runAs?: WorkflowRunAs;
+      authorizer?: 'authenticated';
+    })
+  | (ConfigBase & {
+      trigger: RecordEventTrigger | RecordScheduleTrigger | ScheduledTrigger | WorkflowEventTrigger;
+      runAs: Exclude<WorkflowRunAs, 'session'>;
+    })
+  | (ConfigBase & { trigger: ManualTrigger; runAs?: Exclude<WorkflowRunAs, 'session'> })
+  | (ConfigBase & { trigger: RecordLifecycleTrigger });

package/dist/index.js

@@ -0,0 +1,33 @@
+// The configuration helpers. The workspace build reads these calls as static
+// data, so the helpers only return their argument. A Vite build or a Node
+// script that imports a configuration file runs them.
+//
+// Each function must not refer to anything outside its own body:
+// scripts/lib/runtime-build/app-modules.mjs copies their source into the
+// workspace modules that a page or a workflow imports.
+
+export const defineConfig = (config) => config;
+
+export const defineResource = (resource) => resource;
+
+export const definePage = (page, _component) => page;
+
+export const defineEmail = (email, _component) => email;
+
+export const defineNavigation = (navigation) => navigation;
+
+export const field = {
+  text: (options = {}) => ({ $field: 'text', ...options }),
+  longText: (options = {}) => ({ $field: 'text', ...options }),
+  email: (options = {}) => ({ $field: 'email', ...options }),
+  number: (options = {}) => ({ $field: 'number', ...options }),
+  boolean: (options = {}) => ({ $field: 'boolean', ...options }),
+  date: (options = {}) => ({ $field: 'date', ...options }),
+  datetime: (options = {}) => ({ $field: 'datetime', ...options }),
+  phone: (options = {}) => ({ $field: 'phone', ...options }),
+  url: (options = {}) => ({ $field: 'url', ...options }),
+  select: (options) => ({ $field: 'select', ...options }),
+  money: (options = {}) => ({ $field: 'money', ...options }),
+  markdown: (options = {}) => ({ $field: 'markdown', ...options }),
+  relation: (options) => ({ $field: 'relation', ...options })
+};