opacacms 0.1.0

package/src/schema/fields/base.ts

@@ -0,0 +1,164 @@
+import type { BaseField, FieldAccessConfig } from "../../types";
+
+/**
+ * The base class for all Fluent API Field Builders.
+ * Accumulates configuration state linearly.
+ *
+ * @template TType The literal string type of the field (e.g., 'text', 'relationship').
+ * @template TName The literal string name of the field.
+ * @template TValue The TypeScript literal value type this field produces (e.g., string, number).
+ */
+export abstract class FieldBuilder<
+  TType extends string,
+  TName extends string = string,
+  TValue = any,
+  TSubFields extends readonly any[] = any[],
+> {
+  // Brands for type inference (never used at runtime)
+  public declare readonly __type: TType;
+  public declare readonly __name: TName;
+  public declare readonly __value: TValue;
+  public declare readonly __sub: TSubFields;
+
+  protected config: Partial<BaseField & Record<string, any>> = {};
+
+  constructor(
+    public readonly type: TType,
+    public readonly name: TName,
+  ) {
+    this.config = { type, name };
+  }
+
+  /**
+   * Defines a user-friendly label for the Admin UI.
+   */
+  public label(label: string): this {
+    this.config.label = label;
+    return this;
+  }
+
+  /**
+   * Sets the placeholder text for the input field.
+   */
+  public placeholder(text: string): this {
+    this.config.placeholder = text;
+    return this;
+  }
+
+  /**
+   * Marks the field as strictly required.
+   */
+  public required(val = true): this {
+    this.config.required = val;
+    return this;
+  }
+
+  /**
+   * Marks the field as unique within the database table.
+   */
+  public unique(val = true): this {
+    this.config.unique = val;
+    return this;
+  }
+
+  /**
+   * Enables native field-level internationalization.
+   */
+  public localized(val = true): this {
+    this.config.localized = val;
+    return this;
+  }
+
+  /**
+   * Sets a default value for the field.
+   */
+  public defaultValue(val: TValue): this {
+    this.config.defaultValue = val;
+    return this;
+  }
+
+  /**
+   * A custom validation callback function.
+   */
+  public validate(fn: (value: unknown) => boolean | string): this {
+    this.config.validate = fn;
+    return this;
+  }
+
+  /**
+   * Configure granular access control for this specific field.
+   */
+  public access(config: FieldAccessConfig): this {
+    this.config.access = config;
+    return this;
+  }
+
+  /**
+   * Add a descriptive text below the field in the Admin UI.
+   */
+  public description(text: string): this {
+    this._ensureAdmin();
+    this.config.admin!.description = text;
+    return this;
+  }
+
+  /**
+   * Override Admin UI with custom React components.
+   */
+  public admin(opts: NonNullable<BaseField["admin"]>): this {
+    this._ensureAdmin();
+    this.config.admin = { ...this.config.admin, ...opts };
+    return this;
+  }
+
+  /**
+   * Completely hide the field from the Admin UI and API responses (depending on access).
+   */
+  public hidden(val = true): this {
+    this._ensureAdmin();
+    this.config.admin!.hidden = val;
+    return this;
+  }
+
+  /**
+   * Mark the field as read-only in the Admin UI.
+   */
+  public readOnly(val = true): this {
+    this._ensureAdmin();
+    this.config.admin!.readOnly = val;
+    return this;
+  }
+
+  /**
+   * Spreads arbitrary runtime configuration for any non-strongly-typed features.
+   */
+  public extend(opts: Record<string, any>): this {
+    this.config = { ...this.config, ...opts };
+    return this;
+  }
+
+  /**
+   * Helper to ensure the `admin` options object is initialized.
+   */
+  protected _ensureAdmin() {
+    if (!this.config.admin) {
+      this.config.admin = {};
+    }
+  }
+
+  /**
+   * Helper to ensure the `options` object is initialized.
+   */
+  protected _ensureOptions() {
+    if (!this.config.options) {
+      this.config.options = {};
+    }
+  }
+
+  /**
+   * Compiles the accumulated builder state down into the raw Object structure expected by OpacaCMS.
+   */
+  public build(): any {
+    return this.config;
+  }
+}

package/src/schema/fields/index.ts

@@ -0,0 +1,427 @@
+import { FieldBuilder } from "./base";
+
+export class TextFieldBuilder<TName extends string> extends FieldBuilder<"text", TName, string> {
+  constructor(name: TName) {
+    super("text", name);
+  }
+}
+
+export class SlugFieldBuilder<TName extends string> extends FieldBuilder<"slug", TName, string> {
+  constructor(name: TName) {
+    super("slug", name);
+  }
+
+  public from(sourceField: string): this {
+    (this.config as any).from = sourceField;
+    return this;
+  }
+
+  public format(fn: (val: string) => string): this {
+    (this.config as any).format = fn;
+    return this;
+  }
+}
+
+export class TextAreaFieldBuilder<TName extends string> extends FieldBuilder<
+  "textarea",
+  TName,
+  string
+> {
+  constructor(name: TName) {
+    super("textarea", name);
+  }
+}
+
+export class NumberFieldBuilder<TName extends string> extends FieldBuilder<
+  "number",
+  TName,
+  number
+> {
+  constructor(name: TName) {
+    super("number", name);
+  }
+
+  public min(val: number): this {
+    this._ensureOptions();
+    this.config.options!.min = val;
+    return this;
+  }
+
+  public max(val: number): this {
+    this._ensureOptions();
+    this.config.options!.max = val;
+    return this;
+  }
+}
+
+export class BooleanFieldBuilder<TName extends string> extends FieldBuilder<
+  "boolean",
+  TName,
+  boolean
+> {
+  constructor(name: TName) {
+    super("boolean", name);
+  }
+
+  public display(type: "switch" | "toggle" | "checkbox" | "select"): this {
+    this._ensureOptions();
+    this.config.options!.display = type;
+    return this;
+  }
+}
+
+export class RichTextFieldBuilder<TName extends string> extends FieldBuilder<
+  "richtext",
+  TName,
+  string
+> {
+  constructor(name: TName) {
+    super("richtext", name);
+  }
+
+  public mode(mode: "simple" | "notion"): this {
+    this._ensureOptions();
+    this.config.options!.defaultMode = mode;
+    return this;
+  }
+}
+
+export class RelationshipFieldBuilder<TName extends string> extends FieldBuilder<
+  "relationship",
+  TName,
+  string | string[]
+> {
+  constructor(name: TName) {
+    super("relationship", name);
+  }
+
+  public to(collection: string | { slug: string }): this {
+    this.config.relationTo = typeof collection === "string" ? collection : collection.slug;
+    return this;
+  }
+
+  public single(): this {
+    this.config.hasMany = false;
+    return this;
+  }
+
+  public many(): this {
+    this.config.hasMany = true;
+    return this;
+  }
+
+  public displayField(field: string): this {
+    this.config.displayField = field;
+    return this;
+  }
+}
+
+export class FileFieldBuilder<TName extends string> extends FieldBuilder<"file", TName, unknown> {
+  constructor(name: TName) {
+    super("file", name);
+  }
+
+  public bucket(bucketName: string): this {
+    this.config.bucket = bucketName;
+    return this;
+  }
+
+  public allowedmime_types(types: string[]): this {
+    this._ensureOptions();
+    this.config.options!.allowedmime_types = types;
+    return this;
+  }
+
+  public maxSize(bytes: number): this {
+    this._ensureOptions();
+    this.config.options!.maxFileSize = bytes;
+    return this;
+  }
+}
+
+export class DateFieldBuilder<TName extends string> extends FieldBuilder<
+  "date",
+  TName,
+  string | Date
+> {
+  constructor(name: TName) {
+    super("date", name);
+  }
+}
+
+export class SelectFieldBuilder<TName extends string> extends FieldBuilder<
+  "select",
+  TName,
+  string
+> {
+  constructor(name: TName) {
+    super("select", name);
+  }
+
+  public choices(choices: string[] | { label: string; value: string }[]): this {
+    this._ensureOptions();
+    this.config.options!.choices = choices;
+    return this;
+  }
+}
+
+export class RadioFieldBuilder<TName extends string> extends FieldBuilder<"radio", TName, string> {
+  constructor(name: TName) {
+    super("radio", name);
+  }
+
+  public choices(choices: string[] | { label: string; value: string }[]): this {
+    this._ensureOptions();
+    this.config.options.choices = choices;
+    return this;
+  }
+}
+
+export class TabsFieldBuilder<TTabs extends readonly any[] = []> extends FieldBuilder<
+  "tabs",
+  "",
+  unknown,
+  TTabs
+> {
+  constructor() {
+    super("tabs", "");
+    this.config.tabs = [];
+  }
+
+  public tab<TLabel extends string, TSub extends readonly FieldBuilder<any, any, any, any>[]>(
+    label: TLabel,
+    ...fields: TSub
+  ): TabsFieldBuilder<[...TTabs, { label: TLabel; fields: TSub }]> {
+    this.config.tabs.push({
+      label,
+      fields: fields.map((f) => f.build()),
+    });
+    return this as any;
+  }
+}
+
+export class CollapsibleFieldBuilder<
+  TNames extends string = string,
+  TSub extends readonly any[] = any[],
+> extends FieldBuilder<"collapsible", "", unknown, TSub> {
+  constructor(fields?: FieldBuilder<any, TNames, any, any>[]) {
+    super("collapsible", "");
+    this.config.fields = fields ? fields.map((f) => f.build()) : [];
+    this._ensureOptions();
+  }
+
+  public initiallyCollapsed(val = true): this {
+    this.config.options!.initiallyCollapsed = val;
+    return this;
+  }
+
+  public useAsTitle(fieldName: TNames | (string & {})): this {
+    this.config.options!.useAsTitle = fieldName;
+    return this;
+  }
+
+  public fields<NewSub extends readonly FieldBuilder<any, any, any>[]>(
+    ...fields: NewSub
+  ): CollapsibleFieldBuilder<ExtractNames<NewSub>, NewSub> {
+    this.config.fields = fields.map((f) => f.build());
+    return this as any;
+  }
+}
+
+type ExtractNames<T extends readonly any[]> = T[number]["name"];
+
+export class JoinFieldBuilder<TName extends string> extends FieldBuilder<"join", TName, any[]> {
+  constructor(name: TName) {
+    super("join", name);
+  }
+
+  public collection(collectionSlug: string): this {
+    this.config.collection = collectionSlug;
+    return this;
+  }
+
+  public on(fieldName: string): this {
+    this.config.on = fieldName;
+    return this;
+  }
+}
+
+export class ArrayFieldBuilder<
+  TName extends string,
+  TSub extends readonly any[] = any[],
+> extends FieldBuilder<"array", TName, unknown[], TSub> {
+  constructor(name: TName) {
+    super("array", name);
+  }
+
+  public of<NewSub extends readonly FieldBuilder<any, any, any, any>[]>(
+    ...fields: NewSub
+  ): ArrayFieldBuilder<TName, NewSub> {
+    this.config.fields = fields.map((f) => f.build());
+    return this as any;
+  }
+}
+
+export class GroupFieldBuilder<
+  TName extends string,
+  TNames extends string = string,
+  TSub extends readonly any[] = any[],
+> extends FieldBuilder<"group", TName, Record<string, any>, TSub> {
+  constructor(name: TName, fields?: FieldBuilder<any, TNames, any, any>[]) {
+    super("group", name);
+    if (fields) {
+      this.config.fields = fields.map((f) => f.build());
+    }
+  }
+
+  public fields<NewSub extends readonly FieldBuilder<any, any, any, any>[]>(
+    ...fields: NewSub
+  ): GroupFieldBuilder<TName, ExtractNames<NewSub>, NewSub> {
+    this.config.fields = fields.map((f) => f.build());
+    return this as any;
+  }
+}
+
+export class RowFieldBuilder<TSub extends readonly any[] = any[]> extends FieldBuilder<
+  "row",
+  "",
+  unknown,
+  TSub
+> {
+  constructor(fields?: FieldBuilder<any, any, any, any>[]) {
+    super("row", "");
+    if (fields) {
+      this.config.fields = fields.map((f) => f.build());
+    }
+  }
+
+  public fields<NewSub extends readonly FieldBuilder<any, any, any, any>[]>(
+    ...fields: NewSub
+  ): RowFieldBuilder<NewSub> {
+    this.config.fields = fields.map((f) => f.build());
+    return this as any;
+  }
+}
+
+// Block Builder for Blocks Field
+export class BlockBuilder<
+  TSlug extends string,
+  TNames extends string = string,
+  TSub extends readonly any[] = any[],
+> {
+  private config: Record<string, any>;
+
+  constructor(slug: TSlug) {
+    this.config = { slug, fields: [] };
+  }
+
+  public label(label: string): this {
+    this.config.label = label;
+    return this;
+  }
+
+  public fields<NewSub extends readonly FieldBuilder<any, any, any, any>[]>(
+    ...fields: NewSub
+  ): BlockBuilder<TSlug, ExtractNames<NewSub>, NewSub> {
+    this.config.fields = fields.map((f) => f.build());
+    return this as any;
+  }
+
+  public build() {
+    return this.config;
+  }
+}
+
+export class VirtualFieldBuilder<TName extends string, TData = any> extends FieldBuilder<
+  "virtual",
+  TName,
+  any
+> {
+  constructor(name: TName) {
+    super("virtual", name);
+  }
+
+  public resolve(
+    fn: (args: {
+      data: TData;
+      req: any;
+      user: any;
+      session: any;
+      apiKey?: any;
+    }) => any | Promise<any>,
+  ): this {
+    this.config.resolve = fn;
+    return this;
+  }
+
+  public returnType(type: "string" | "number" | "boolean" | "json"): this {
+    this.config.returnType = type;
+    return this;
+  }
+}
+
+export class BlocksFieldBuilder<
+  TName extends string,
+  TBlocks extends readonly any[] = any[],
+> extends FieldBuilder<"blocks", TName, any[], TBlocks> {
+  constructor(name: TName) {
+    super("blocks", name);
+  }
+
+  public blocks<NewBlocks extends readonly BlockBuilder<any, any, any>[]>(
+    ...blocks: NewBlocks
+  ): BlocksFieldBuilder<TName, NewBlocks> {
+    this.config.blocks = blocks.map((b) => b.build());
+    return this as any;
+  }
+}
+
+/**
+ * The Field Factory object containing methods to instantiate specific field builders.
+ */
+export const Field = {
+  text: <N extends string>(name: N) => new TextFieldBuilder<N>(name),
+  slug: <N extends string>(name: N) => new SlugFieldBuilder<N>(name),
+  textarea: <N extends string>(name: N) => new TextAreaFieldBuilder<N>(name),
+  number: <N extends string>(name: N) => new NumberFieldBuilder<N>(name),
+  boolean: <N extends string>(name: N) => new BooleanFieldBuilder<N>(name),
+  date: <N extends string>(name: N) => new DateFieldBuilder<N>(name),
+  select: <N extends string>(name: N) => new SelectFieldBuilder<N>(name),
+  radio: <N extends string>(name: N) => new RadioFieldBuilder<N>(name),
+  richText: <N extends string>(name: N) => new RichTextFieldBuilder<N>(name),
+  relationship: <N extends string>(name: N) => new RelationshipFieldBuilder<N>(name),
+  join: <N extends string>(name: N) => new JoinFieldBuilder<N>(name),
+  file: <N extends string>(name: N) => new FileFieldBuilder<N>(name),
+  array: <N extends string>(name: N) => new ArrayFieldBuilder<N>(name),
+  group: <N extends string, TSub extends readonly FieldBuilder<any, any, any, any>[]>(
+    name: N,
+    fields?: TSub,
+  ) => {
+    const builder = new GroupFieldBuilder<N, any, TSub>(name);
+    if (fields) builder.fields(...(fields as any));
+    return builder;
+  },
+  tabs: () => new TabsFieldBuilder(),
+  collapsible: <N extends string, S extends readonly FieldBuilder<any, any, any, any>[]>(
+    fields?: S,
+  ) => {
+    const builder = new CollapsibleFieldBuilder<ExtractNames<S>, S>(fields as any);
+    return builder;
+  },
+  row: <S extends readonly FieldBuilder<any, any, any, any>[]>(fields?: S) => {
+    const builder = new RowFieldBuilder<S>(fields as any);
+    return builder;
+  },
+  blocks: <N extends string, TSub extends readonly BlockBuilder<any, any, any>[]>(
+    name: N,
+    ...blocks: TSub
+  ) => {
+    const builder = new BlocksFieldBuilder<N, TSub>(name);
+    builder.blocks(...(blocks as any));
+    return builder;
+  },
+  block: <N extends string>(slug: N) => new BlockBuilder<N>(slug),
+};
+
+// Also export the base builders if extensions are needed
+export * from "./base";