@stndrds/schema 1.0.0-alpha.294 → 1.0.0-alpha.68

package/dist/attributes-CWPLbp7c.d.mts

@@ -1,584 +0,0 @@
-import { IconName, CountryIso3, CurrencyCode, ColorId } from '@stndrds/constants';
-import { Uuid } from './utils.mjs';
-
-type ComputedFormulaAstNode = ComputedFormulaLiteralNode | ComputedFormulaPathNode | ComputedFormulaCallNode | ComputedFormulaBinaryNode;
-interface ComputedFormulaLiteralNode {
-    kind: "literal";
-    value: string | number | boolean | null;
-}
-interface ComputedFormulaPathNode {
-    kind: "path";
-    parts: string[];
-}
-interface ComputedFormulaCallNode {
-    kind: "call";
-    functionName: string;
-    args: ComputedFormulaAstNode[];
-}
-interface ComputedFormulaBinaryNode {
-    kind: "binary";
-    operator: ComputedFormulaBinaryOperator;
-    left: ComputedFormulaAstNode;
-    right: ComputedFormulaAstNode;
-}
-type ComputedFormulaBinaryOperator = ">" | "<" | ">=" | "<=" | "==" | "!=" | "+" | "-" | "*" | "/";
-declare class ComputedFormulaParseError extends Error {
-    constructor(message: string);
-}
-declare function parseComputedFormula(expression: string): ComputedFormulaAstNode;
-
-type ComputedReturnType = "text" | "number" | "boolean" | "date" | "select" | "multiselect";
-type ComputedFieldKind = "formula" | "rollup";
-type ComputedValueType = {
-    kind: "scalar";
-    type: Exclude<ComputedReturnType, "multiselect">;
-} | {
-    kind: "collection";
-    itemType: "text" | "number" | "boolean" | "date" | "select";
-};
-interface ComputedOptionsSource {
-    objectName: string;
-    attributeName: string;
-    attributeId?: string;
-}
-type ComputedDependency = {
-    kind: "local";
-    attributeName: string;
-} | {
-    kind: "relation";
-    relationName: string;
-    targetAttributeName?: string;
-    cardinality?: "one" | "many";
-} | {
-    kind: "computed";
-    attributeName: string;
-} | {
-    kind: "options";
-    source: ComputedOptionsSource;
-};
-interface ComputedPlan {
-    kind: ComputedFieldKind;
-    attributeName: string;
-    expression: string;
-    returnType: ComputedReturnType;
-    valueType: ComputedValueType;
-    dependencies: ComputedDependency[];
-    optionsSource?: ComputedOptionsSource;
-    targetAttributeType?: AttributeType;
-    dependenciesHash: string;
-    ast?: ComputedFormulaAstNode;
-}
-
-/**
- * Allowed attribute types in .qualifyWith()
- *
- * IMPORTANT: Complex types (formula, rollup, relation, file, user, document, richtext)
- * are NOT supported to avoid duplicating backend behavior.
- */
-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.
- */
-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({ name: "companies", label: "Companies" })
- *   .to("companies").many()
- *   .qualifyWith(
- *     select({ name: "role", label: "Role" }).options([...]).required(),
- *     number({ name: "shares", label: "Shares" }).min(0),
- *   )
- * ```
- */
-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[]`).
- */
-declare function resolvePropertyDefinitions(attr: unknown): PropertyAttribute[];
-/**
- * Property attribute types that have an `options` array.
- */
-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);
- *     }
- *   }
- * }
- * ```
- */
-declare function hasOptions(attr: PropertyAttribute): attr is OptionPropertyAttribute;
-
-declare const ATTRIBUTE_TYPES: readonly ["text", "richtext", "number", "checkbox", "date", "phone", "currency", "status", "location", "select", "multiselect", "user", "relation", "formula", "rollup", "document"];
-type AttributeType = (typeof ATTRIBUTE_TYPES)[number];
-/**
- * Status group categorization
- */
-type StatusGroup = "idle" | "in_progress" | "finished";
-/**
- * Unified option type for select-like fields
- */
-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
- */
-interface AttributeGroup {
-    id: string;
-    label: string;
-    description?: string;
-    attributeIds: string[];
-    collapsible?: boolean;
-    collapsed?: boolean;
-    order?: number;
-}
-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>;
-}
-interface TextAttribute extends BaseAttribute<string> {
-    type: "text";
-    multiline?: boolean;
-    minLength?: number;
-    maxLength?: number;
-    pattern?: string;
-    format?: "email" | "url" | "slug";
-}
-type NumberUnit = "integer" | "decimal" | "percentage";
-interface NumberAttribute extends BaseAttribute<number> {
-    type: "number";
-    min?: number;
-    max?: number;
-    unit?: NumberUnit;
-    decimals?: number;
-    renderAs?: "number" | "rating";
-}
-interface CheckboxAttribute extends BaseAttribute<boolean> {
-    type: "checkbox";
-}
-type DateFormat = "short" | "long" | "full" | "relative";
-type DateValue = string | "today";
-type TimeFormat = "12h" | "24h";
-/** Stored value of a date attribute configured with `.endDate()`. */
-interface DateRangeValue {
-    start: string;
-    end: string | null;
-}
-interface DateAttribute extends BaseAttribute<string | DateRangeValue> {
-    type: "date";
-    dateFormat?: DateFormat;
-    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;
-}
-interface Phone {
-    countryCode: CountryIso3;
-    phoneNumber: string;
-}
-interface PhoneAttribute extends BaseAttribute<Phone> {
-    type: "phone";
-    defaultCountryCode?: CountryIso3;
-}
-interface Currency {
-    code: CurrencyCode;
-    value: number;
-}
-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
- */
-interface StatusAttribute extends BaseAttribute<string> {
-    type: "status";
-    options: Option[];
-}
-interface Location {
-    address?: string;
-    address2?: string;
-    city?: string;
-    state?: string;
-    postalCode?: string;
-    country?: CountryIso3;
-    latitude?: number;
-    longitude?: number;
-}
-type LocationGranularity = "full" | "address" | "city" | "state" | "country" | "coordinates";
-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
- */
-interface SelectAttribute extends BaseAttribute<string> {
-    type: "select";
-    options: Option[];
-    renderAs?: "badges";
-}
-interface MultiselectAttribute extends BaseAttribute<string[]> {
-    type: "multiselect";
-    options: Option[];
-    renderAs?: "badges";
-}
-type UserReferenceType = "user" | "agent";
-interface UserAttribute extends BaseAttribute<string | string[]> {
-    type: "user";
-    types?: UserReferenceType[];
-    multiple?: boolean;
-}
-/**
- * Wildcard marker for universal relations (can link to any object)
- * Use with `.toAny()` builder method
- */
-declare const RELATION_TARGET_ANY: "*";
-/**
- * Configuration for bilateral synchronization (bidirectional relations)
- */
-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";
-    /** 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
- */
-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
- */
-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
- */
-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({ name: "company", label: "Company" })
- *   .to("companies")
- *   .required()
- * // → Value: "rec-uuid-123" | null
- * ```
- *
- * @example Multi relation (many-to-many)
- * ```typescript
- * relation({ name: "contacts", label: "Contacts" })
- *   .to("contacts", { displayTemplate: "{firstName} {lastName}" })
- *   .many()
- *   .maxItems(5)
- * // → Value: ["rec-1", "rec-2", ...]
- * ```
- *
- * @example Polymorphic relation (multiple target objects)
- * ```typescript
- * relation({ name: "linked", label: "Linked Items" })
- *   .to("companies")
- *   .to("contacts")
- *   .to("deals")
- *   .many()
- * // → Can link to records from any of these objects
- * ```
- */
-type RelationAttribute = SingleRelationAttribute | MultiRelationAttribute;
-/**
- * Check if a relation attribute is universal (can link to any object)
- * Universal relations have `targets: [{ object: "*" }]`
- */
-declare function isUniversalRelation(attr: RelationAttribute): boolean;
-/**
- * Check if a relation attribute has bilateral synchronization enabled
- */
-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)
- */
-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({ name: "content", label: "Content" }).required()
- * ```
- */
-interface RichtextAttribute extends BaseAttribute<string> {
-    type: "richtext";
-}
-type RichTextAttribute = RichtextAttribute;
-/**
- * Return type for formula expressions
- */
-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({ name: "total", label: "Total" })
- *   .expression("price * quantity")
- *   .returns("number")
- *   .decimals(2)
- * ```
- *
- * @example With functions
- * ```typescript
- * formula({ name: "fullName", label: "Full Name" })
- *   .expression("CONCAT(firstName, ' ', lastName)")
- *   .returns("text")
- * ```
- */
-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;
-    /** 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
- */
-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({ name: "totalOrders", label: "Total Orders" })
- *   .from("orders")           // relation attribute name
- *   .aggregate("amount")      // target attribute to sum
- *   .using("sum")
- *   .decimals(2)
- * ```
- *
- * @example Count of related records
- * ```typescript
- * rollup({ name: "orderCount", label: "Number of Orders" })
- *   .from("orders")
- *   .using("count")
- * ```
- */
-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 */
-    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({ name: "contracts", label: "Contrats" })
- *   .accepts(["application/pdf"])
- * ```
- */
-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.
- */
-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.
- */
-declare function isAttributeSortable(attr: {
-    type: AttributeType;
-}): boolean;
-
-export { type OptionPropertyAttribute as $, type Attribute as A, type BilateralConfig as B, type CurrencyAttribute as C, type DateAttribute as D, ATTRIBUTE_TYPES as E, type FormulaAttribute as F, type AttributeGroup as G, type BaseAttribute as H, type ComputedFieldKind as I, type ComputedFormulaBinaryNode as J, type ComputedFormulaBinaryOperator as K, type LocationAttribute as L, type MultiRelationAttribute as M, type NumberAttribute as N, type Option as O, type PhoneAttribute as P, type ComputedFormulaCallNode as Q, type RelationAttribute as R, type SingleRelationAttribute as S, type TextAttribute as T, type UserAttribute as U, type ComputedFormulaLiteralNode as V, ComputedFormulaParseError as W, type ComputedFormulaPathNode as X, type DateFormat as Y, type DateValue as Z, type NumberUnit as _, type RichtextAttribute as a, type PropertyType as a0, RELATION_TARGET_ANY as a1, type RichTextAttribute as a2, type StatusGroup as a3, hasOptions as a4, inferInverseCardinality as a5, isAttributeSortable as a6, isBilateralRelation as a7, isUniversalRelation as a8, parseComputedFormula as a9, resolvePropertyDefinitions as aa, type MultiselectAttribute as b, type SelectAttribute as c, type StatusAttribute as d, type RollupAttribute as e, type AttributeType as f, type CheckboxAttribute as g, type ComputedValueType as h, type ComputedReturnType as i, type ComputedOptionsSource as j, type ComputedDependency as k, type ComputedPlan as l, type ComputedFormulaAstNode as m, type LocationGranularity as n, type Location as o, type DateRangeValue as p, type DocumentAttribute as q, type Phone as r, type Currency as s, type PropertySchema as t, type TimeFormat as u, type PropertyAttribute as v, type FormulaReturnType as w, type RelationTarget as x, type RollupFunction as y, type UserReferenceType as z };