@rippling/rippling-sdk 0.2.0-alpha.82 → 0.2.0-alpha.84

package/src/core/platform/manifest/custom-objects/page-layout.ts

@@ -0,0 +1,380 @@
+import {
+  CustomObjectPageLayout,
+  type CustomObjectFieldSection,
+  type CustomObjectPageLayoutProps,
+  type CustomTab,
+  type FieldsSection,
+  type PageLayoutSection,
+  type PageLayoutTab,
+  type SectionField,
+  type SectionFieldInput,
+  type SystemSectionEdit,
+  type SystemTabEdit,
+  type TabEdits,
+  type TabWithSections,
+} from '../../../../lib/manifest';
+import type { AnyCustomObjectDefinition } from '../../custom-objects/types';
+import type { ManifestRegistration } from './types';
+import type { TypedManifestFieldInput } from './field-resolution';
+import { resolveTypedManifestField } from './field-resolution';
+
+/**
+ * Field object accepted inside typed page-layout field arrays.
+ *
+ * @typeParam TDefinition - Object definition whose valid field inputs should be enforced.
+ */
+export interface TypedSectionField<TDefinition extends AnyCustomObjectDefinition>
+  extends Omit<SectionField, 'field'> {
+  /** Field to display, expressed as a typed field-name string or manifest field reference. */
+  readonly field: TypedManifestFieldInput<TDefinition>;
+}
+
+/**
+ * Field-array entry accepted by typed page-layout helpers.
+ *
+ * @typeParam TDefinition - Object definition whose valid field inputs should be enforced.
+ */
+export type TypedSectionFieldInput<TDefinition extends AnyCustomObjectDefinition> =
+  | TypedManifestFieldInput<TDefinition>
+  | TypedSectionField<TDefinition>;
+
+/**
+ * `fields_section` shape accepted by the typed page-layout helper.
+ *
+ * @typeParam TDefinition - Object definition whose valid field arrays should be enforced.
+ */
+export interface TypedFieldsSection<TDefinition extends AnyCustomObjectDefinition>
+  extends Omit<FieldsSection, 'fields'> {
+  /** Fields to display in this section, expressed using typed field-name strings or manifest field refs. */
+  readonly fields: readonly TypedSectionFieldInput<TDefinition>[];
+}
+
+/**
+ * Page-layout section shape accepted by the typed page-layout helper.
+ *
+ * Only `fields_section.fields` is specialized in this first pass; other section
+ * variants continue to use the low-level manifest shapes unchanged.
+ *
+ * @typeParam TDefinition - Object definition whose valid field arrays should be enforced.
+ */
+export type TypedPageLayoutSection<TDefinition extends AnyCustomObjectDefinition> =
+  | TypedFieldsSection<TDefinition>
+  | Exclude<PageLayoutSection, FieldsSection>;
+
+/**
+ * Tab-with-sections shape accepted by the typed page-layout helper.
+ *
+ * @typeParam TDefinition - Object definition whose valid field arrays should be enforced.
+ */
+export interface TypedTabWithSections<TDefinition extends AnyCustomObjectDefinition>
+  extends Omit<TabWithSections, 'sections'> {
+  /** Sections inside this tab. */
+  readonly sections: readonly TypedPageLayoutSection<TDefinition>[];
+}
+
+/**
+ * Tab shape accepted by the typed page-layout helper.
+ *
+ * @typeParam TDefinition - Object definition whose valid field arrays should be enforced.
+ */
+export type TypedPageLayoutTab<TDefinition extends AnyCustomObjectDefinition> =
+  | TypedTabWithSections<TDefinition>
+  | CustomTab;
+
+/**
+ * System-section edit shape accepted by the typed page-layout helper.
+ *
+ * @typeParam TDefinition - Object definition whose valid field arrays should be enforced.
+ */
+export interface TypedSystemSectionEdit<TDefinition extends AnyCustomObjectDefinition>
+  extends Omit<SystemSectionEdit, 'newFields'> {
+  /** Fields to append to the target system section. */
+  readonly newFields?: readonly TypedSectionFieldInput<TDefinition>[];
+}
+
+/**
+ * System-tab edit shape accepted by the typed page-layout helper.
+ *
+ * @typeParam TDefinition - Object definition whose valid field arrays should be enforced.
+ */
+export interface TypedSystemTabEdit<TDefinition extends AnyCustomObjectDefinition>
+  extends Omit<SystemTabEdit, 'newSections' | 'systemSectionEdits'> {
+  /** New sections to add to the target system tab. */
+  readonly newSections?: readonly TypedPageLayoutSection<TDefinition>[];
+  /** Edits to built-in sections inside the target system tab. */
+  readonly systemSectionEdits?: Readonly<Record<string, TypedSystemSectionEdit<TDefinition>>>;
+}
+
+/**
+ * `tabEdits` shape accepted by the typed page-layout helper.
+ *
+ * @typeParam TDefinition - Object definition whose valid field arrays should be enforced.
+ */
+export interface TypedTabEdits<TDefinition extends AnyCustomObjectDefinition>
+  extends Omit<TabEdits, 'newTabs' | 'systemTabEdits'> {
+  /** New tabs to add to the layout. */
+  readonly newTabs?: readonly TypedPageLayoutTab<TDefinition>[];
+  /** Edits to existing system tabs. */
+  readonly systemTabEdits?: Readonly<Record<string, TypedSystemTabEdit<TDefinition>>>;
+}
+
+/**
+ * Initialization properties for {@link defineTypedPageLayout}.
+ *
+ * This first pass focuses on the common field-array surfaces:
+ * - `tabEdits.newTabs[].sections[].fields`
+ * - `tabEdits.systemTabEdits.*.newSections[].fields`
+ * - `tabEdits.systemTabEdits.*.systemSectionEdits.*.newFields`
+ *
+ * Other page-layout configuration remains identical to the low-level manifest API.
+ *
+ * @typeParam TDefinition - Object definition whose valid field arrays should be enforced.
+ */
+export interface TypedCustomObjectPageLayoutProps<TDefinition extends AnyCustomObjectDefinition>
+  extends Omit<CustomObjectPageLayoutProps, 'tabEdits'> {
+  /** Typed page-layout tab edits. */
+  readonly tabEdits?: TypedTabEdits<TDefinition>;
+}
+
+/**
+ * Initialization properties for {@link defineBasicTypedPageLayout}.
+ *
+ * This is the typed equivalent of {@link CustomObjectPageLayout.basic}: a
+ * single-tab, single-section layout for the common case where callers do not
+ * need to customize tab structure.
+ *
+ * @typeParam TDefinition - Object definition whose valid field inputs should be enforced.
+ */
+export interface TypedBasicPageLayoutProps<TDefinition extends AnyCustomObjectDefinition> {
+  /** Optional existing manifest section that should own every listed field. */
+  readonly section?: CustomObjectFieldSection;
+  /** Optional fields to place in the generated General section. */
+  readonly fields?: readonly TypedManifestFieldInput<TDefinition>[];
+}
+
+/**
+ * Returns whether one typed page-layout field entry uses the object form with additional section metadata.
+ *
+ * @param value - Typed section-field input to inspect.
+ * @returns Whether the entry is the object-shaped variant.
+ * @typeParam TDefinition - Object definition whose field inputs are being inspected.
+ */
+function isTypedSectionField<TDefinition extends AnyCustomObjectDefinition>(
+  value: TypedSectionFieldInput<TDefinition>,
+): value is TypedSectionField<TDefinition> {
+  return typeof value === 'object' && value != null && 'field' in value;
+}
+
+/**
+ * Resolves one typed page-layout field input into the low-level manifest field representation.
+ *
+ * @param registration - Manifest registration produced from the typed object definition.
+ * @param entry - Typed page-layout field input to resolve.
+ * @returns Low-level manifest section-field input.
+ * @typeParam TDefinition - Object definition whose field inputs are being resolved.
+ */
+function resolveTypedSectionFieldInput<TDefinition extends AnyCustomObjectDefinition>(
+  registration: ManifestRegistration<TDefinition>,
+  entry: TypedSectionFieldInput<TDefinition>,
+): SectionFieldInput {
+  if (isTypedSectionField(entry)) {
+    return {
+      ...entry,
+      field: resolveTypedManifestField(registration, entry.field),
+    };
+  }
+  return resolveTypedManifestField(registration, entry);
+}
+
+/**
+ * Returns whether one page-layout section is the `fields_section` variant handled by the typed helper.
+ *
+ * @param section - Typed page-layout section to inspect.
+ * @returns Whether the section carries a typed `fields` array.
+ * @typeParam TDefinition - Object definition whose section is being inspected.
+ */
+function isFieldsSection<TDefinition extends AnyCustomObjectDefinition>(
+  section: TypedPageLayoutSection<TDefinition>,
+): section is TypedFieldsSection<TDefinition> {
+  return section.type === 'fields_section';
+}
+
+/**
+ * Resolves one typed page-layout section into the low-level manifest section shape.
+ *
+ * @param registration - Manifest registration produced from the typed object definition.
+ * @param section - Typed page-layout section to resolve.
+ * @returns Low-level manifest page-layout section.
+ * @typeParam TDefinition - Object definition whose section is being resolved.
+ */
+function resolveTypedPageLayoutSection<TDefinition extends AnyCustomObjectDefinition>(
+  registration: ManifestRegistration<TDefinition>,
+  section: TypedPageLayoutSection<TDefinition>,
+): PageLayoutSection {
+  if (!isFieldsSection(section)) {
+    return section as PageLayoutSection;
+  }
+
+  const { fields, ...rest } = section;
+  return {
+    ...rest,
+    fields: fields.map((entry) => resolveTypedSectionFieldInput(registration, entry)),
+  };
+}
+
+/**
+ * Resolves one typed page-layout tab into the low-level manifest tab shape.
+ *
+ * @param registration - Manifest registration produced from the typed object definition.
+ * @param tab - Typed page-layout tab to resolve.
+ * @returns Low-level manifest page-layout tab.
+ * @typeParam TDefinition - Object definition whose tab is being resolved.
+ */
+function resolveTypedPageLayoutTab<TDefinition extends AnyCustomObjectDefinition>(
+  registration: ManifestRegistration<TDefinition>,
+  tab: TypedPageLayoutTab<TDefinition>,
+): PageLayoutTab {
+  if (tab.type !== 'tab_with_sections') return tab;
+  return {
+    ...tab,
+    sections: tab.sections.map((section) => resolveTypedPageLayoutSection(registration, section)),
+  };
+}
+
+/**
+ * Resolves one typed system-section edit into the low-level manifest edit shape.
+ *
+ * @param registration - Manifest registration produced from the typed object definition.
+ * @param edit - Typed system-section edit to resolve.
+ * @returns Low-level manifest system-section edit.
+ * @typeParam TDefinition - Object definition whose edit is being resolved.
+ */
+function resolveTypedSystemSectionEdit<TDefinition extends AnyCustomObjectDefinition>(
+  registration: ManifestRegistration<TDefinition>,
+  edit: TypedSystemSectionEdit<TDefinition>,
+): SystemSectionEdit {
+  const { newFields, ...rest } = edit;
+  return {
+    ...rest,
+    ...(newFields != null ?
+      { newFields: newFields.map((entry) => resolveTypedSectionFieldInput(registration, entry)) }
+    : {}),
+  };
+}
+
+/**
+ * Resolves one typed system-tab edit into the low-level manifest edit shape.
+ *
+ * @param registration - Manifest registration produced from the typed object definition.
+ * @param edit - Typed system-tab edit to resolve.
+ * @returns Low-level manifest system-tab edit.
+ * @typeParam TDefinition - Object definition whose edit is being resolved.
+ */
+function resolveTypedSystemTabEdit<TDefinition extends AnyCustomObjectDefinition>(
+  registration: ManifestRegistration<TDefinition>,
+  edit: TypedSystemTabEdit<TDefinition>,
+): SystemTabEdit {
+  const { newSections, systemSectionEdits: rawSystemSectionEdits, ...rest } = edit;
+  const systemSectionEdits =
+    rawSystemSectionEdits == null ? undefined : (
+      Object.fromEntries(
+        Object.entries(rawSystemSectionEdits).map(([sectionKey, sectionEdit]) => [
+          sectionKey,
+          resolveTypedSystemSectionEdit(registration, sectionEdit),
+        ]),
+      )
+    );
+
+  return {
+    ...rest,
+    ...(newSections != null ?
+      { newSections: newSections.map((section) => resolveTypedPageLayoutSection(registration, section)) }
+    : {}),
+    ...(systemSectionEdits != null ? { systemSectionEdits } : {}),
+  };
+}
+
+/**
+ * Resolves the typed `tabEdits` surface into the low-level manifest representation.
+ *
+ * @param registration - Manifest registration produced from the typed object definition.
+ * @param tabEdits - Typed tab edits to resolve.
+ * @returns Low-level manifest tab-edits object.
+ * @typeParam TDefinition - Object definition whose tab edits are being resolved.
+ */
+function resolveTypedTabEdits<TDefinition extends AnyCustomObjectDefinition>(
+  registration: ManifestRegistration<TDefinition>,
+  tabEdits: TypedTabEdits<TDefinition>,
+): TabEdits {
+  const { newTabs, systemTabEdits: rawSystemTabEdits, ...rest } = tabEdits;
+  const systemTabEdits =
+    rawSystemTabEdits == null ? undefined : (
+      Object.fromEntries(
+        Object.entries(rawSystemTabEdits).map(([tabKey, edit]) => [
+          tabKey,
+          resolveTypedSystemTabEdit(registration, edit),
+        ]),
+      )
+    );
+
+  return {
+    ...rest,
+    ...(newTabs != null ?
+      { newTabs: newTabs.map((tab) => resolveTypedPageLayoutTab(registration, tab)) }
+    : {}),
+    ...(systemTabEdits != null ? { systemTabEdits } : {}),
+  };
+}
+
+/**
+ * Registers a typed page layout for a manifest custom object.
+ *
+ * This helper sits on top of the low-level {@link CustomObjectPageLayout}
+ * manifest class. It preserves the runtime behavior of that class while adding
+ * object-specific string-literal IntelliSense for the most common field-array
+ * authoring surfaces.
+ *
+ * @param registration - Manifest registration produced from the typed object definition.
+ * @param props - Typed page-layout properties to materialize into the manifest class.
+ * @returns Low-level manifest page-layout instance with typed field arrays resolved.
+ * @typeParam TDefinition - Object definition whose valid field arrays should be enforced.
+ */
+export function defineTypedPageLayout<TDefinition extends AnyCustomObjectDefinition>(
+  registration: ManifestRegistration<TDefinition>,
+  props: TypedCustomObjectPageLayoutProps<TDefinition>,
+): CustomObjectPageLayout {
+  const layoutProps: CustomObjectPageLayoutProps = {
+    apiName: props.apiName,
+    name: props.name,
+    ...(props.tabEdits != null ? { tabEdits: resolveTypedTabEdits(registration, props.tabEdits) } : {}),
+    ...(props.headerEdits != null ? { headerEdits: props.headerEdits } : {}),
+    ...(props.visibilityConditions != null ? { visibilityConditions: props.visibilityConditions } : {}),
+    ...(props.layoutId != null ? { layoutId: props.layoutId } : {}),
+    ...(props.blueprintKey != null ? { blueprintKey: props.blueprintKey } : {}),
+  };
+  return new CustomObjectPageLayout(registration.object, layoutProps);
+}
+
+/**
+ * Registers the common single-tab "basic" layout using typed field-name strings.
+ *
+ * Use this helper when the low-level {@link CustomObjectPageLayout.basic}
+ * behavior is sufficient and you want the shortest typed path from schema to a
+ * working page layout.
+ *
+ * @param registration - Manifest registration produced from the typed object definition.
+ * @param props - Optional basic-layout properties.
+ * @returns Low-level manifest page-layout instance created through `CustomObjectPageLayout.basic(...)`.
+ * @typeParam TDefinition - Object definition whose valid field inputs should be enforced.
+ */
+export function defineBasicTypedPageLayout<TDefinition extends AnyCustomObjectDefinition>(
+  registration: ManifestRegistration<TDefinition>,
+  props: TypedBasicPageLayoutProps<TDefinition> = {},
+): CustomObjectPageLayout {
+  return CustomObjectPageLayout.basic(registration.object, {
+    ...(props.section != null ? { section: props.section } : {}),
+    ...(props.fields != null ?
+      { fields: props.fields.map((field) => resolveTypedManifestField(registration, field)) }
+    : {}),
+  });
+}