@proteos/sdk 0.55.0 → 0.57.0

package/src/meta/layout/elements.ts

@@ -24,6 +24,7 @@ export const LayoutElementType = {
   List: 'list',
   WorkflowTrigger: 'workflow_trigger',
   SchedulingPicker: 'scheduling_picker',
+  Calendar: 'calendar',
 } as const
 export type LayoutElementType = (typeof LayoutElementType)[keyof typeof LayoutElementType]
 
@@ -276,6 +277,50 @@ export type SchedulingPickerElement = CommonProps & {
   is_header_hidden?: boolean
 }
 
+/** The grid views a `calendar` element can show; mirrors `metamodel.CalendarViewKinds`. */
+export const CALENDAR_VIEW_KINDS = ['day', 'week', 'month', 'agenda'] as const
+export type CalendarViewKind = (typeof CALENDAR_VIEW_KINDS)[number]
+
+/**
+ * Cap on `overlay_user_ids` (one team colour per overlaid user); mirrors
+ * `metamodel.CalendarMaxOverlayUsers`.
+ */
+export const CALENDAR_MAX_OVERLAY_USERS = 8
+
+/**
+ * A user's calendar embedded in a page: the in-page counterpart of
+ * `/org/:orgId/calendar`. `user_id` is `$current_user`, a Liquid template over
+ * the page scope (`{{ record.owner.id }}`) or a literal user id; writes (new
+ * event, drag, edit) are offered only when it resolves to the viewer — unless
+ * `is_hosted_create_allowed` opens creation through the displayed user.
+ */
+export type CalendarElement = CommonProps & {
+  type: 'calendar'
+  user_id: string
+  /** Initial view; `day` when absent. */
+  default_view?: CalendarViewKind
+  /** Views the switcher offers; only `default_view` when absent. Must contain it. */
+  views?: CalendarViewKind[]
+  /** Liquid template for the initial anchor day (day key or datetime); today when absent. */
+  date?: string
+  /**
+   * Record pages only: show only events linked to the page record
+   * (`record_entity_slug` + `record_id`) instead of the user's whole calendar.
+   */
+  is_record_scoped?: boolean
+  /**
+   * Up to `CALENDAR_MAX_OVERLAY_USERS` further users drawn on the same grid in
+   * team colours, read-only. Each resolves like `user_id`.
+   */
+  overlay_user_ids?: string[]
+  /**
+   * When the calendar shows someone else: "New event" and drag-select create
+   * THROUGH that user (the viewer hosts the request, the event lands on the
+   * displayed user's calendar). Edit and move stay owner-only.
+   */
+  is_hosted_create_allowed?: boolean
+}
+
 export type TextVariant = 'heading' | 'subheading' | 'body' | 'caption' | 'callout' | 'block-title'
 
 export type TextElement = CommonProps & {
@@ -300,6 +345,7 @@ export type LayoutElement =
   | ListElement
   | WorkflowTriggerElement
   | SchedulingPickerElement
+  | CalendarElement
 
 // ──────────────────────────────────────────────────────────── Schemas ──
 
@@ -439,5 +485,16 @@ export const LayoutElementSchema: z.ZodType<LayoutElement> = z.lazy(() =>
       contact_id: z.string().optional(),
       is_header_hidden: z.boolean().optional(),
     }),
+    z.object({
+      type: z.literal('calendar'),
+      ...commonPropsShape,
+      user_id: z.string().min(1),
+      default_view: z.enum(CALENDAR_VIEW_KINDS).optional(),
+      views: z.array(z.enum(CALENDAR_VIEW_KINDS)).min(1).optional(),
+      date: z.string().optional(),
+      is_record_scoped: z.boolean().optional(),
+      overlay_user_ids: z.array(z.string().min(1)).max(CALENDAR_MAX_OVERLAY_USERS).optional(),
+      is_hosted_create_allowed: z.boolean().optional(),
+    }),
   ]),
 ) as unknown as z.ZodType<LayoutElement>

package/src/meta/layout/index.ts

@@ -17,6 +17,10 @@ export {
   lookupPrimaryControl,
 } from './control-registry.js'
 export {
+  CALENDAR_MAX_OVERLAY_USERS,
+  CALENDAR_VIEW_KINDS,
+  type CalendarElement,
+  type CalendarViewKind,
   type CardElement,
   type ColumnElement,
   type ComponentElement,
@@ -29,17 +33,19 @@ export {
   LayoutTabSchema,
   type ListElement,
   type RecordFilterElement,
-  type SchedulingPickerElement,
-  type WorkflowTriggerElement,
   type RelatedListElement,
   type RelatedRecordElement,
   type RowElement,
+  type SchedulingPickerElement,
   type SectionElement,
   type TabsElement,
   type TextElement,
   type TextVariant,
+  type WorkflowTriggerElement,
 } from './elements.js'
 export {
+  isPageBackground,
+  PAGE_BACKGROUND_COLOR_RE,
   PAGE_BACKGROUND_TOKENS,
   type PageBackgroundToken,
   type PageLayout,
@@ -49,4 +55,13 @@ export {
   type PageStyle,
   PageStyleSchema,
 } from './page-layout.js'
-export { type SizeValue, SizeValueSchema } from './size-value.js'
+export {
+  isLengthValue,
+  isStyleSizeValue,
+  type LengthValue,
+  LengthValueSchema,
+  type SizeValue,
+  SizeValueSchema,
+  type StyleSizeValue,
+  StyleSizeValueSchema,
+} from './size-value.js'

package/src/meta/layout/page-layout.ts

@@ -1,6 +1,11 @@
 import { z } from 'zod'
 import { type LayoutElement, LayoutElementSchema } from './elements.js'
-import { type SizeValue, SizeValueSchema } from './size-value.js'
+import {
+  type SizeValue,
+  SizeValueSchema,
+  type StyleSizeValue,
+  StyleSizeValueSchema,
+} from './size-value.js'
 
 /**
  * Side panel slot. Rendered as a sticky-by-default right rail; collapses
@@ -44,6 +49,26 @@ export const PAGE_BACKGROUND_TOKENS = [
 
 export type PageBackgroundToken = (typeof PAGE_BACKGROUND_TOKENS)[number]
 
+/**
+ * A raw CSS color a page background may use instead of a token: a hex literal
+ * or one of a few color functions with a restricted argument charset (no `;{}`,
+ * no `url(`), so a background can never smuggle arbitrary CSS. Keep in sync
+ * with `pageBackgroundColorRe` in the metadata-service layout validator.
+ */
+export const PAGE_BACKGROUND_COLOR_RE =
+  /^(#[0-9a-fA-F]{3,8}|(rgb|rgba|hsl|hsla|oklch|oklab)\([0-9a-zA-Z.,%/ +-]+\))$/
+
+/** True when `text` is a background the server accepts: a token or a color
+ *  matching PAGE_BACKGROUND_COLOR_RE, at most 64 characters. */
+export function isPageBackground(text: string): boolean {
+  const value = text.trim()
+  if (value.length === 0 || value.length > 64) return false
+  return (
+    (PAGE_BACKGROUND_TOKENS as readonly string[]).includes(value) ||
+    PAGE_BACKGROUND_COLOR_RE.test(value)
+  )
+}
+
 /**
  * Per-page presentation of a standalone page shell: background color plus the
  * content container's max-width and side / top padding. Every field is
@@ -56,20 +81,24 @@ export type PageBackgroundToken = (typeof PAGE_BACKGROUND_TOKENS)[number]
  * area rather than a standalone shell.
  */
 export interface PageStyle {
-  /** Design-token key (see PAGE_BACKGROUND_TOKENS) or a raw CSS color. */
+  /** Design-token key (see PAGE_BACKGROUND_TOKENS) or a raw CSS color
+   *  matching PAGE_BACKGROUND_COLOR_RE. */
   background?: string
-  /** Content max-width; `"fill"` / `"auto"` removes the cap. */
-  max_width?: SizeValue
+  /** Content max-width; `"fill"` / `"auto"` removes the cap. Never a fraction. */
+  max_width?: StyleSizeValue
   /** Horizontal / vertical padding of the content container (Tailwind px/py). */
-  padding_x?: SizeValue
-  padding_y?: SizeValue
+  padding_x?: StyleSizeValue
+  padding_y?: StyleSizeValue
 }
 
 export const PageStyleSchema = z.object({
-  background: z.string().optional(),
-  max_width: SizeValueSchema.optional(),
-  padding_x: SizeValueSchema.optional(),
-  padding_y: SizeValueSchema.optional(),
+  background: z
+    .string()
+    .refine(isPageBackground, 'must be a design token or a hex / rgb / hsl / oklch / oklab color')
+    .optional(),
+  max_width: StyleSizeValueSchema.optional(),
+  padding_x: StyleSizeValueSchema.optional(),
+  padding_y: StyleSizeValueSchema.optional(),
 })
 
 /**

package/src/meta/layout/size-value.ts

@@ -21,6 +21,43 @@ export type SizeValue =
 
 const SIZE_VALUE_STRING_RE = /^(\d+\/\d+|\d+px|\d+%|auto|fill)$/
 
+/**
+ * A fixed CSS length — the subset of SizeValue the server accepts for
+ * `min_height` ("Npx" / "N%"). Mirrors `minHeightStringRe` in the
+ * metadata-service layout validator.
+ */
+export type LengthValue = `${number}px` | `${number}%`
+
+const LENGTH_VALUE_RE = /^(\d+px|\d+%)$/
+
+export function isLengthValue(text: string): text is LengthValue {
+  return LENGTH_VALUE_RE.test(text)
+}
+
+export const LengthValueSchema: z.ZodType<LengthValue> = z
+  .string()
+  .regex(LENGTH_VALUE_RE, 'must match Npx or N%') as unknown as z.ZodType<LengthValue>
+
+/**
+ * A page-style dimension (`layout.style.max_width` / `padding_*`): a length,
+ * "auto" or "fill" — never a fraction. Mirrors `styleSizeValueStringRe` in the
+ * metadata-service layout validator.
+ */
+export type StyleSizeValue = LengthValue | 'auto' | 'fill'
+
+const STYLE_SIZE_VALUE_RE = /^(\d+px|\d+%|auto|fill)$/
+
+export function isStyleSizeValue(text: string): text is StyleSizeValue {
+  return STYLE_SIZE_VALUE_RE.test(text)
+}
+
+export const StyleSizeValueSchema: z.ZodType<StyleSizeValue> = z
+  .string()
+  .regex(
+    STYLE_SIZE_VALUE_RE,
+    'must match Npx, N%, "auto", or "fill"',
+  ) as unknown as z.ZodType<StyleSizeValue>
+
 export const SizeValueSchema: z.ZodType<SizeValue> = z.union([
   z.number().min(0).max(1).describe('Fraction in [0, 1]'),
   z.string().regex(SIZE_VALUE_STRING_RE, 'must match n/m, Npx, N%, "auto", or "fill"'),

package/src/meta/types.ts

@@ -2046,6 +2046,22 @@ export interface DesignReferenceContent {
  * hook. An object rather than a bare string because a bare string IS a valid
  * user value (clients send bare ids). Mirrors `metamodel.CurrentUserDefault`.
  */
+/**
+ * The signed-in user as a VALUE: a `FilterElement.value` (any field —
+ * data-service and the page renderer substitute the caller's id), a component
+ * prop, a `calendar` element's `user_id` / `overlay_user_ids`, a string
+ * literal in the records SQL dialect. The `$` prefix keeps it apart from every
+ * id, slug or text, so no slot has to know the attribute type. The Liquid
+ * scope exposes the same person as the object `{{ current_user.id }}`.
+ * Mirrors `common.CurrentUser`.
+ */
+export const CURRENT_USER = '$current_user'
+
+/** True when a string slot carries the current-user sentinel. */
+export function isCurrentUser(value: unknown): value is typeof CURRENT_USER {
+  return value === CURRENT_USER
+}
+
 export const CURRENT_USER_DEFAULT = { type: 'current_user' } as const
 export type CurrentUserDefault = { type: 'current_user' }