Overview

import { defineCollection, defineTextField, defineRichTextField, defineRelationshipField } from '@dyrected/core'

export const Posts = defineCollection({
  slug: 'posts',
  fields: [
    defineTextField({ name: 'title', label: 'Title', required: true }),
    defineRichTextField({ name: 'body', label: 'Body' }),
    defineRelationshipField({ name: 'author', label: 'Author', relationTo: 'users' }),
  ],
})

export type AuthDocFields = {
  email: string;
  password?: string;
  roles?: string[];
};

export interface BaseFieldAdmin {
  /** Placeholder text shown when the input has no value. */
  placeholder?: string;
  /** For nested object-like fields, choose which child field should summarize the value in admin surfaces. */
  useAsTitle?: string;
  /** Custom component key registered in the Admin UI. */
  component?: string;
  /** Help text rendered below the field. */
  description?: string;
  /** Hides the field from the Admin form without deleting stored data. */
  hidden?: boolean;
  /** Excludes the field from Admin list filtering. */
  filterable?: boolean;
  /** Renders the field as non-editable in the Admin UI. */
  readOnly?: boolean;
  /** Hides the field's label in the Admin form (e.g. single-field array rows where the label is redundant). */
  hideLabel?: boolean;
  /** Reactive condition controlling whether the field is visible in the Admin UI. */
  condition?:
    | ((
        data: Record<string, unknown>,
        siblingData: Record<string, unknown>,
      ) => boolean)
    | string;
  /** Tab name used when the edit form is rendered as tabs. */
  tab?: string;
  /** CSS width hint used when the field appears inside a `row`. */
  width?: string;
}

export type CharacterLimitFieldAdmin = {
  /** Admin-only compatibility alias for `field.maxLength`. Prefer the top-level field property. */
  maxLength?: number;
};

export interface CharacterLimitFieldConfig {
  /** Advisory maximum character count exposed to editors and client tooling. */
  maxLength?: number;
}

export type DynamicOptionItem = string | { label: string; value: unknown };

export interface DynamicOptionsConfig {
  /** Resolver function executed on the server to produce option items. */
  resolve: DynamicOptionsResolver;
  /** Cache duration in seconds for identical resolver calls. */
  cacheTTL?: number;
}

export type DynamicOptionsResolver = (
  args: DynamicOptionsResolverArgs,
) => Promise<DynamicOptionItem[]> | DynamicOptionItem[];

export interface DynamicOptionsResolverArgs {
  /** Database adapter available to server-side option resolvers. */
  db?: DatabaseAdapter;
  /** Authenticated user making the request, if any. */
  user?: AuthenticatedUser;
  /** Current HTTP request context, including query parameters. */
  req: HookRequestContext;
}

export type Field =
  | TextField
  | TextareaField
  | EmailField
  | UrlField
  | IconField
  | DateField
  | DateTimeField
  | TimeField
  | SelectField
  | RadioField
  | NumberField
  | BooleanField
  | MultiSelectField
  | RelationshipField
  | ImageField
  | RichTextField
  | JsonField
  | ObjectField
  | ArrayField
  | BlocksField
  | JoinField
  | RowField;

export interface FieldBase {
  /** Stored key for this field. Omit only for layout-only fields such as `row` or `join`. */
  name?: string;
  /** Human-readable label shown in the Admin UI. */
  label?: string;
  /** Whether the field must have a value when saving. */
  required?: boolean;
  /** Whether values for this field must be unique across the collection. */
  unique?: boolean;
  /** Default value used when a new document omits this field. */
  defaultValue?: unknown;
  /** Static or dynamic option source for supported selection fields. */
  options?:
    | string[]
    | { label: string; value: unknown }[]
    | DynamicOptionsResolver
    | DynamicOptionsConfig;
  /** Target collection slug for `relationship` fields. */
  relationTo?: string;
  /** Whether the field stores multiple values instead of one. */
  hasMany?: boolean;
  /** Child fields for `object` and `array` field types. */
  fields?: Field[];
  /** Allowed block definitions for a `blocks` field. */
  blocks?: Block[];
  /**
   * Shared block slugs pulled from the root `defineConfig({ blocks: [...] })`
   * registry for a `blocks` field.
   *
   * Use this when the same block types should be reused across multiple fields
   * without inlining the full block schema into each field definition.
   */
  blockReferences?: string[];
  /** Target collection slug for `join` fields. */
  collection?: string;
  /** Back-reference field name on the joined collection. */
  on?: string;
  /** Maximum number of joined documents returned by a `join` field. */
  limit?: number;
  /** Field-level read, create, and update access rules. Supports functions, Jexl strings, booleans, and named policies. */
  access?: {
    /** Controls whether this field is returned in API responses. */
    read?: AccessRule;
    /** Controls whether this field may be set when creating a document. Falls back to `update` when omitted. */
    create?: AccessRule;
    /** Controls whether incoming writes may change this field on update. */
    update?: AccessRule;
  };
  /** Admin-only presentation options for this field. */
  admin?: BaseFieldAdmin;
  /** Previous storage key this field falls back to. When the field has no value, its value is read from the old key at read time, then rewritten under the new key on the next save. */
  renameTo?: string;
  /** Whether SQL adapters should promote this field into a first-class column. */
  promoted?: boolean;
}

export type FieldType =
  | "text"
  | "textarea"
  | "richText"
  | "number"
  | "boolean"
  | "date"
  | "datetime"
  | "time"
  | "select"
  | "multiSelect"
  | "radio"
  | "relationship"
  | "array"
  | "object"
  | "json"
  | "blocks"
  | "image"
  | "email"
  | "url"
  | "icon"
  | "join"
  | "row";

export type InferDocShape<Fields extends readonly Field[]> = Fields extends readonly []
  ? Record<never, never>
  : Fields extends readonly [infer Head extends Field, ...infer Tail extends readonly Field[]]
    ? InferFieldEntry<Head> & InferDocShape<Tail>
    : Record<string, unknown>;

export type NumberLimitFieldAdmin = {
  /** Admin-only compatibility alias for `field.min`. Prefer the top-level field property. */
  min?: number;
  /** Admin-only compatibility alias for `field.max`. Prefer the top-level field property. */
  max?: number;
};

export interface NumberLimitFieldConfig {
  /** Advisory minimum numeric value exposed to editors and client tooling. */
  min?: number;
  /** Advisory maximum numeric value exposed to editors and client tooling. */
  max?: number;
}

export type SystemDocFields = {
  createdAt?: string;
  updatedAt?: string;
  createdBy?: string;
  updatedBy?: string;
};

export type TypedField<
  TType extends FieldType,
  TValue,
  TAdminExtra = Record<never, never>,
> = Omit<FieldBase, "admin"> & {
  type: TType;
  admin?: BaseFieldAdmin & TAdminExtra;
} & FieldHooks<TValue> &
  FieldAdminHooks<TValue>;

export type UploadDocFields = {
  filename: string;
  filesize?: number;
  mimeType: string;
  url: string;
  width?: number;
  height?: number;
  focalPoint?: { x: number; y: number };
  blurhash?: string;
  sizes?: Record<string, { filename?: string; url?: string; width?: number; height?: number }>;
};

export type WordLimitFieldAdmin = {
  /** Admin-only compatibility alias for `field.maxWords`. Prefer the top-level field property. */
  maxWords?: number;
};

export interface WordLimitFieldConfig {
  /** Advisory maximum word count exposed to editors and client tooling. */
  maxWords?: number;
}