@standards/schema 1.0.0-alpha.413 → 1.0.0-alpha.415

package/dist/attributes-DW19xkoM.d.ts

@@ -1,561 +0,0 @@
-
-import { Uuid } from "./utils-CChBw_3d.js";
-import { ColorId, CountryIso3, CurrencyCode, IconName } from "@standards/constants";
-//#region src/types/computed.d.ts
-export declare const COMPUTED_RETURN_TYPES: readonly ["text", "number", "boolean", "date", "select", "multiselect"];
-export type ComputedReturnType = (typeof COMPUTED_RETURN_TYPES)[number];
-export interface ComputedOptionsSource {
-  objectName: string;
-  attributeName: string;
-  attributeId?: string;
-}
-//#endregion
-//#region src/types/relation-properties.d.ts
-/**
- * Allowed attribute types in .qualifyWith()
- *
- * IMPORTANT: Complex types (formula, rollup, relation, file, user, document, richtext)
- * are NOT supported to avoid duplicating backend behavior.
- */
-export type PropertyType = "text" | "number" | "checkbox" | "date" | "phone" | "currency" | "status" | "select" | "multiselect" | "location";
-/**
- * Union of attribute types allowed as qualified relation properties.
- *
- * These are the same Attribute types used for object attributes,
- * restricted to simple types that don't require complex backend duplication.
- */
-export type PropertyAttribute = TextAttribute | NumberAttribute | CheckboxAttribute | DateAttribute | PhoneAttribute | CurrencyAttribute | StatusAttribute | SelectAttribute | MultiselectAttribute | LocationAttribute;
-/**
- * Schema defining properties for a qualified relation.
- *
- * Uses the same Attribute types as object attributes, enabling DRY builders:
- *
- * @example
- * ```typescript
- * relation("companies", "Companies")
- *   .to("companies").many()
- *   .qualifyWith(
- *     select("role", "Role").options([...]).required(),
- *     number("shares", "Shares").min(0),
- *   )
- * ```
- */
-export interface PropertySchema {
-  definitions: PropertyAttribute[];
-}
-/**
- * Normalizes an attribute's `properties` field to a flat list of
- * {@link PropertyAttribute}. Handles both the production {@link PropertySchema}
- * shape (`{ definitions: [...] }`) and the raw-array shape used in test
- * fixtures (`PropertyAttribute[]`).
- */
-export declare function resolvePropertyDefinitions(attr: unknown): PropertyAttribute[];
-/**
- * Property attribute types that have an `options` array.
- */
-export type OptionPropertyAttribute = SelectAttribute | StatusAttribute | MultiselectAttribute;
-/**
- * Type guard to check if a property attribute has options.
- *
- * @param attr - The property attribute to check
- * @returns true if the attribute is a select, status, or multiselect type with options
- *
- * @example
- * ```typescript
- * for (const def of definitions) {
- *   if (hasOptions(def)) {
- *     // TypeScript knows def.options exists and is Option[]
- *     for (const option of def.options) {
- *       console.log(option.value);
- *     }
- *   }
- * }
- * ```
- */
-export declare function hasOptions(attr: PropertyAttribute): attr is OptionPropertyAttribute;
-//#endregion
-//#region src/types/attributes.d.ts
-export declare const ATTRIBUTE_TYPES: readonly ["text", "richtext", "number", "checkbox", "date", "phone", "currency", "status", "location", "select", "multiselect", "user", "relation", "formula", "rollup", "document"];
-export type AttributeType = (typeof ATTRIBUTE_TYPES)[number];
-/**
- * Status group categorization
- */
-export type StatusGroup = "idle" | "in_progress" | "finished";
-/**
- * Unified option type for select-like fields
- */
-export interface Option {
-  value: string;
-  label: string;
-  color?: ColorId;
-  description?: string;
-  group?: StatusGroup;
-  /** Value of the inverse option for bilateral relations (e.g. "parent" → "child") */
-  inverse?: string;
-  archived?: boolean;
-}
-/**
- * Attribute grouping for UI organization
- */
-export interface AttributeGroup {
-  id: string;
-  label: string;
-  description?: string;
-  attributeIds: string[];
-  collapsible?: boolean;
-  collapsed?: boolean;
-  order?: number;
-}
-export interface BaseAttribute<DefaultValueType = unknown> {
-  id?: Uuid;
-  objectId?: Uuid;
-  name: string;
-  label: string;
-  type: AttributeType;
-  required?: boolean;
-  placeholder?: string;
-  description?: string;
-  defaultValue?: DefaultValueType;
-  icon?: IconName;
-  order?: number;
-  hidden?: boolean;
-  archived?: boolean;
-  deprecated?: boolean;
-  system?: boolean;
-  unique?: boolean;
-  metadata?: Record<string, unknown>;
-}
-export interface TextAttribute extends BaseAttribute<string> {
-  type: "text";
-  multiline?: boolean;
-  minLength?: number;
-  maxLength?: number;
-  pattern?: string;
-  format?: "email" | "url" | "slug";
-}
-export type NumberUnit = "integer" | "decimal" | "percentage";
-export interface NumberAttribute extends BaseAttribute<number> {
-  type: "number";
-  min?: number;
-  max?: number;
-  unit?: NumberUnit;
-  decimals?: number;
-  renderAs?: "number" | "rating";
-}
-export interface CheckboxAttribute extends BaseAttribute<boolean> {
-  type: "checkbox";
-}
-export type DateFormat = "short" | "long" | "full" | "relative";
-export type DateValue = string | "today";
-export type TimeFormat = "12h" | "24h";
-/** Stored value of a date attribute configured with `.endDate()`. */
-export interface DateRangeValue {
-  start: string;
-  end: string | null;
-}
-/**
- * How much of a calendar date the value is meant to carry. The stored value is
- * always a full day; a narrower precision says the day (and the month, for a
- * year) is not part of the fact.
- */
-export type DatePrecision = "day" | "month" | "year";
-export interface DateAttribute extends BaseAttribute<string | DateRangeValue> {
-  type: "date";
-  dateFormat?: DateFormat;
-  /** Defaults to "day". Refused with `includeTime` or `endDate` when narrower. */
-  precision?: DatePrecision;
-  minDate?: DateValue;
-  maxDate?: DateValue;
-  /** Values carry a time component; stored as full ISO UTC datetimes. */
-  includeTime?: boolean;
-  /** Values are ranges stored as { start, end } objects. */
-  endDate?: boolean;
-  /** Display format for the time component. Defaults to "24h". */
-  timeFormat?: TimeFormat;
-}
-export interface Phone {
-  countryCode: CountryIso3;
-  phoneNumber: string;
-}
-export interface PhoneAttribute extends BaseAttribute<Phone> {
-  type: "phone";
-  defaultCountryCode?: CountryIso3;
-}
-export interface Currency {
-  code: CurrencyCode;
-  value: number;
-}
-export interface CurrencyAttribute extends BaseAttribute<Currency> {
-  type: "currency";
-  defaultCurrency?: CurrencyCode;
-  allowedCurrencies?: CurrencyCode[];
-  /** Allow negative currency values (e.g. refunds, credits). Defaults to false. */
-  allowNegative?: boolean;
-}
-/**
- * StatusAttribute - For workflow states with semantic grouping (idle/in_progress/finished)
- * Use this for: Task status, Order status, Project phases, Process states
- * Use SelectAttribute for: Categories, Types, simple choices without workflow
- */
-export interface StatusAttribute extends BaseAttribute<string> {
-  type: "status";
-  options: Option[];
-}
-export interface Location {
-  address?: string;
-  address2?: string;
-  city?: string;
-  state?: string;
-  postalCode?: string;
-  country?: CountryIso3;
-  latitude?: number;
-  longitude?: number;
-}
-export type LocationGranularity = "full" | "address" | "city" | "state" | "country" | "coordinates";
-export interface LocationAttribute extends BaseAttribute<Location> {
-  type: "location";
-  granularity?: LocationGranularity;
-  defaultCountry?: CountryIso3;
-  allowedCountries?: CountryIso3[];
-}
-/**
- * SelectAttribute - For simple single-choice selection
- * Use this for: Categories, Document types, Departments, Priorities
- * Options can be grouped (e.g., countries by continent) but no workflow logic
- */
-export interface SelectAttribute extends BaseAttribute<string> {
-  type: "select";
-  options: Option[];
-  renderAs?: "badges";
-}
-export interface MultiselectAttribute extends BaseAttribute<string[]> {
-  type: "multiselect";
-  options: Option[];
-  renderAs?: "badges";
-}
-export type UserReferenceType = "user" | "agent";
-export interface UserAttribute extends BaseAttribute<string | string[]> {
-  type: "user";
-  types?: UserReferenceType[];
-  multiple?: boolean;
-  /** Each person added to the value is notified (`record.assigned`), when they can read the record. */
-  notifiesOnAssign?: boolean;
-  /**
-   * The value holds actor ids — members and agents, within `types` — named by
-   * each actor's current display name rather than looked up as users. (The
-   * built-in `createdBy` / `lastUpdatedBy` also name API keys and the system.)
-   */
-  actors?: boolean;
-}
-/**
- * Wildcard marker for universal relations (can link to any object)
- * Use with `.toAny()` builder method
- */
-export declare const RELATION_TARGET_ANY: "*";
-/**
- * Configuration for bilateral synchronization (bidirectional relations)
- */
-export interface BilateralConfig {
-  /** Target object containing the inverse attribute */
-  object: string;
-  /** Name of the inverse attribute */
-  attribute: string;
-  /** Optional cardinality override (inferred by default) */
-  cardinality?: "one" | "many";
-  /** Label for the inverse attribute when it is generated from this declaration. */
-  label?: string;
-  /** When true, this side owns the storage direction for qualified properties.
-   *  Set to false on the inverse side (enriched at read time). */
-  storageOwner?: boolean;
-}
-/**
- * Target object for a relation - defines which objects can be linked
- */
-export interface RelationTarget {
-  /** Object name (e.g., "companies", "contacts") or "*" for any object */
-  object: string;
-  /**
-   * Display template for the label using mustache-like syntax
-   * @example "{name}" or "{firstName} {lastName} — {email}"
-   */
-  displayTemplate?: string;
-  /**
-   * Optional filter to restrict available records
-   * @example { status: "active" }
-   */
-  filter?: Record<string, unknown>;
-}
-/**
- * Base properties shared by both single and multi relation attributes
- *
- * Note: Deletion behavior is always "restrict" - if a record is referenced
- * by other records, it cannot be deleted until those references are removed.
- * This is enforced by RecordService.deleteRecord() which throws
- * RecordReferencedError when attempting to delete a referenced record.
- */
-interface RelationAttributeBase extends Omit<BaseAttribute<unknown>, "defaultValue"> {
-  type: "relation";
-  /** Target objects that can be linked */
-  targets: RelationTarget[];
-  /** Optional properties schema for qualified relations */
-  properties?: PropertySchema;
-  /** Configuration for bilateral synchronization (opt-in) */
-  bilateral?: BilateralConfig;
-}
-/**
- * Single relation attribute (one-to-one or many-to-one)
- * Stores a single record ID or null
- */
-export interface SingleRelationAttribute extends RelationAttributeBase {
-  cardinality: "one";
-  defaultValue?: string | null;
-}
-/**
- * Multi relation attribute (one-to-many or many-to-many)
- * Stores an array of record IDs
- */
-export interface MultiRelationAttribute extends RelationAttributeBase {
-  cardinality: "many";
-  defaultValue?: string[];
-  /** Maximum number of relations allowed */
-  maxItems?: number;
-}
-/**
- * RelationAttribute links to other objects/records
- * Discriminated union by cardinality for type-safe value handling
- *
- * @example Single relation (many-to-one)
- * ```typescript
- * relation("company", "Company")
- *   .to("companies")
- *   .required()
- * // → Value: "rec-uuid-123" | null
- * ```
- *
- * @example Multi relation (many-to-many)
- * ```typescript
- * relation("contacts", "Contacts")
- *   .to("contacts", { displayTemplate: "{firstName} {lastName}" })
- *   .many()
- *   .maxItems(5)
- * // → Value: ["rec-1", "rec-2", ...]
- * ```
- *
- * @example Polymorphic relation (multiple target objects)
- * ```typescript
- * relation("linked", "Linked Items")
- *   .to("companies")
- *   .to("contacts")
- *   .to("deals")
- *   .many()
- * // → Can link to records from any of these objects
- * ```
- */
-export type RelationAttribute = SingleRelationAttribute | MultiRelationAttribute;
-/**
- * Check if a relation attribute is universal (can link to any object)
- * Universal relations have `targets: [{ object: "*" }]`
- */
-/**
- * The object names a relation attribute can point at, universal marker
- * stripped. Any other attribute type — and a relation row whose config lost
- * its `targets` — yields no names.
- */
-export declare function relationTargetsOf(attribute: Attribute): string[];
-export declare function isUniversalRelation(attr: RelationAttribute): boolean;
-/**
- * Check if a relation attribute has bilateral synchronization enabled
- */
-export declare function isBilateralRelation(attr: RelationAttribute): attr is RelationAttribute & {
-  bilateral: BilateralConfig;
-};
-/**
- * Infer the cardinality of the inverse relation
- * - one → many (contact.company ↔ company.contacts)
- * - many → many (contact.tags ↔ tag.contacts)
- */
-export declare function inferInverseCardinality(cardinality: "one" | "many"): "one" | "many";
-/**
- * RichtextAttribute - Rich text content using semantic markdown
- *
- * Stores content as semantic markdown string (with directives like :::callout).
- * Parsed at runtime to Tiptap JSON for editing.
- * Use this for: Notes, articles, descriptions, long-form content.
- *
- * @example
- * ```typescript
- * richtext("content", "Content").required()
- * ```
- */
-export interface RichtextAttribute extends BaseAttribute<string> {
-  type: "richtext";
-}
-/**
- * Return type for formula expressions
- */
-export type FormulaReturnType = ComputedReturnType;
-/**
- * FormulaAttribute - Computed value based on other attributes
- *
- * Formulas are calculated at read-time and are always read-only.
- * Users cannot directly edit formula values.
- *
- * @example Simple calculation
- * ```typescript
- * formula("total", "Total")
- *   .expression("price * quantity")
- *   .returns("number")
- *   .decimals(2)
- * ```
- *
- * @example With functions
- * ```typescript
- * formula("fullName", "Full Name")
- *   .expression("CONCAT(firstName, ' ', lastName)")
- *   .returns("text")
- * ```
- */
-export interface FormulaAttribute extends Omit<BaseAttribute<never>, "defaultValue" | "required"> {
-  type: "formula";
-  /** Expression to evaluate (e.g., "price * quantity") */
-  expression: string;
-  /** Expected return type for formatting */
-  returnType: FormulaReturnType;
-  /** Decimal places for number results */
-  decimals?: number;
-  /**
-   * ISO 4217 code a `number` result renders with — `123 456 €` instead of
-   * `123456` — for a formula over money (#3419). Presentation only: the
-   * stored value stays a number, sort, filter and aggregation are untouched,
-   * and `returnType` stays `"number"` because that IS what the expression
-   * returns. The rollup's `targetCurrencyCode` (#2644), mirrored. Absent →
-   * the bare number, exactly as before.
-   */
-  currencyCode?: CurrencyCode;
-  /** Source attribute for select-like computed options */
-  optionsSource?: ComputedOptionsSource;
-  /** Whether to allow relation references in the expression (e.g., "company.name") */
-  allowRelations?: boolean;
-  /** Formula is always not required (read-only) */
-  required: false;
-}
-/**
- * Aggregation functions for rollup attributes
- *
- * Categories:
- * - Numeric (sum, avg): Only for number and currency types
- * - Date (earliest, latest): Only for date type
- * - Count (count, countValues, countUniqueValues, countEmpty): Universal
- * - Percent (percentEmpty, percentNotEmpty): Universal
- * - Lookup (original): Returns all values as array, rendered as target type
- */
-export type RollupFunction = "sum" | "avg" | "earliest" | "latest" | "count" | "countValues" | "countUniqueValues" | "countEmpty" | "percentEmpty" | "percentNotEmpty" | "original";
-/**
- * RollupAttribute - Aggregates values from related records
- *
- * Rollups are calculated and stored (denormalized) for performance.
- * They are automatically recalculated when related records change.
- * Users cannot directly edit rollup values.
- *
- * @example Sum of related amounts
- * ```typescript
- * rollup("totalOrders", "Total Orders")
- *   .from("orders")           // relation attribute name
- *   .aggregate("amount")      // target attribute to sum
- *   .using("sum")
- *   .decimals(2)
- * ```
- *
- * @example Count of related records
- * ```typescript
- * rollup("orderCount", "Number of Orders")
- *   .from("orders")
- *   .using("count")
- * ```
- */
-export interface RollupAttribute extends Omit<BaseAttribute<never>, "defaultValue" | "required"> {
-  type: "rollup";
-  /** Name of the relation attribute on this object */
-  relationAttribute: string;
-  /**
-   * Dot notation path for multi-level traversal (Phase 4+)
-   * @example "orders.items" - traverse through orders to items
-   */
-  relationPath?: string;
-  /**
-   * Attribute name on the target object to aggregate. Absent for `count`,
-   * which aggregates the linked records themselves (#3571).
-   */
-  targetAttribute?: string;
-  /** Aggregation function to apply */
-  function: RollupFunction;
-  /** Decimal places for numeric results */
-  decimals?: number;
-  /** Rollup is always not required (read-only) */
-  required: false;
-  /**
-   * Cached type of the target attribute for display purposes
-   * Used when function="original" to render values as the target type
-   */
-  targetAttributeType?: AttributeType;
-  /**
-   * Cached currency code of a currency target, from its `defaultCurrency`
-   * (#2644). The stored rollup value stays a bare number; this is the
-   * schema-derived channel that lets a single-code sum/avg render with its
-   * symbol. Absent → the value renders bare, exactly as before.
-   *
-   * Named for what it holds — an ISO 4217 CODE — rather than the siblings'
-   * `targetAttribute*` prefix: `targetAttributeCurrency` would read as a
-   * `Currency` value, which this deliberately is not.
-   */
-  targetCurrencyCode?: CurrencyCode;
-  /**
-   * Cached options from target attribute (for select/status/multiselect display)
-   * Required when function="original" and target is a select-like type
-   */
-  targetAttributeOptions?: Option[];
-  /** Source attribute for select-like computed options */
-  optionsSource?: ComputedOptionsSource;
-}
-/**
- * DocumentAttribute - References structured documents.
- *
- * A DocumentAttribute references packs of anonymous files with typed edge
- * properties.
- *
- * Every document attribute is multi by construction — the underlying storage
- * (documents + files) supports 1 Doc → N files uniformly.
- *
- * @example
- * ```typescript
- * document("contracts", "Contrats")
- *   .accepts(["application/pdf"])
- * ```
- */
-export interface DocumentAttribute extends BaseAttribute<string[]> {
-  type: "document";
-  /**
-   * Schema for typed properties on the record→document edge.
-   * Symmetric with `RelationAttribute.properties`; populated by `.qualifyWith(...)`.
-   * Stored on `record_reference_edges.properties`, not on the document itself.
-   */
-  properties?: PropertySchema;
-  /** MIME prefixes/globs (e.g. "image/*", "application/pdf") applied to every file of the pack. */
-  accepts?: string[];
-  /** Hard ceiling in bytes applied to every file of the pack. */
-  maxFileSize?: number;
-}
-/**
- * Union of every attribute definition supported by Standards objects.
- *
- * Use this type when code needs to inspect or render attributes generically
- * across primitive, relation, computed, user, and document fields.
- */
-export type Attribute = TextAttribute | RichtextAttribute | NumberAttribute | CheckboxAttribute | DateAttribute | PhoneAttribute | CurrencyAttribute | StatusAttribute | LocationAttribute | SelectAttribute | MultiselectAttribute | UserAttribute | RelationAttribute | FormulaAttribute | RollupAttribute | DocumentAttribute;
-/**
- * Check if an attribute supports sorting based on its type.
- */
-export declare function isAttributeSortable(attr: {
-  type: AttributeType;
-}): boolean;
-//#endregion