@calternal/ui

Public UI exports; keep shared controls and picker types beside their component contracts (#412, #506, #723, DESIGN §35).

Classes

SurfaceViewport

The §34 desktop presentation: a wide viewport with a precise pointer.

Extends

• MediaQuery

Constructors

Constructor

new SurfaceViewport(): SurfaceViewport

Returns

SurfaceViewport

Overrides

MediaQuery.constructor

---

Warmth

Constructors

Constructor

new Warmth(now?): Warmth

Parameters

Parameter	Type
now?	() => number

Returns

Warmth

Methods

cool()

cool(): void

Forget the warm state (Escape, a scroll, a press).

Returns

void

delay()

delay(): number

Delay before the next tooltip shows: 0 while warm, else the cold delay.

Returns

number

hidden()

hidden(): void

Returns

void

isWarm()

isWarm(): boolean

Returns

boolean

shown()

shown(): void

Returns

void

Interfaces

ActivityStack

One inline activity deck for a kind, hour and Photo date role.

Properties

Property	Type	Description
added?	boolean	This is the Photo’s upload date, shown as <N> Added (#624).
addedItems?	GridItem[]	Stable Calendar items used by the upload-date preview carousel (#624).
count	number	-
files	CalendarFile[]	-
hour	number	Hour of day, 0–23.
kind	ActivityKind	-
notes	CalendarNote[]	-

---

AttachmentRef

Properties

Property	Type	Description
attachment	CalendarAttachment	-
family	AttachmentFamily	-
fullName	string	Full name for the shared warm tooltip.
key	string	Stable key inside one entry: targets are unique per entry.
kind	"task" | "note" | "file" | "link"	-
label	string	Accessible name of the card’s button.
missing	boolean	The linked local item is absent and must not open as a live file.
name	string	Display name: the link text, else the last path segment.
thumbUrl	string | null	Files thumb route URL, or null for a glyph tile.

---

CalendarAttachment

A file linked under a log entry (- [text](target) child bullet).

Properties

Property	Type	Description
displayName?	string | null	Friendly photo or file title, when the API has one.
embed	boolean	-
fullName?	string | null	Full indexed file name for the shared warm tooltip.
itemId?	string | null	Files item ID (/f/<id>), when the target is indexed and visible.
kind	"task" | "note" | "file"	-
mediaType?	string | null	Indexed media type of the target file.
missing?	boolean	A local target that no longer has a live Files, Note or Task item.
noteId?	string | null	The target Note’s calternal-id (/n/<id>).
target	string	-
text	string	-
thumb?	string | null	Content hash for a supported file’s Files thumbnail.
thumbnailKind?	ThumbnailKind | null	Files renderer kind, so the same content hash selects its own preview.
thumbnailUrl?	string | null	Already validated API thumbnail URL for standalone Calendar items (#822).

---

CalendarColumnBounds

Sorted horizontal bounds for the rendered Calendar columns. Drag handlers use this binary lookup after capturing layout once per gesture (#751, §39).

Properties

Property	Type
date	string
left	number
right	number

---

CalendarDay

Properties

Property	Type	Description
continuedLogs	CalendarLogPart[]	Render-only Log parts that started on the preceding Daily note.
counts	DayCounts	-
cover	CalendarFile | null	The day’s most recent photo, used as the Month cell’s faint cover.
date	string	-
eventColor	string | null	First visible subscription layer colour for dense day markers.
events	CalendarEvent[]	-
eventTag	string | null	First Event category for dense views that only draw a day dot.
fileHours	HourGroup[]	-
items	GridItem[]	Standalone activity rows for the Week and Day grid, in time order (#589).
logs	CalendarLog[]	-
notes	CalendarNote[]	-
photoHours	HourGroup[]	-
tasks	CalendarTask[]	-

---

CalendarEvent

An Event: planned CalDAV or a read-only URL subscription item (#431).

Properties

Property	Type	Description
allDay	boolean	-
color?	string | null	The User-selected colour of an external subscription layer.
continuesAfter?	boolean	This daily part ends before the Event’s last day.
continuesBefore?	boolean	This daily part starts after the Event’s first day.
end	string | null	-
endsAt?	string | null	-
endsOn?	string | null	-
id	string	-
location?	string | null	Place attached by the Event provider.
provider	string	The Event’s Calendar display name.
readOnly?	boolean	URL-subscribed Events open read-only and can be copied to a CalDAV Calendar.
recurring?	boolean	Recurring Event instances cannot be edited until the API supports occurrence writes (#536).
sourceId?	string | null	Stable URL subscription ID for an external read-only calendar layer.
start	string | null	HH:MM local start, or null for an all-day event.
startsAt?	string | null	The whole event’s start and end (RFC 3339), when it spans more than this day’s part.
startsOn?	string | null	Full all-day occurrence bounds, with an exclusive end date.
tags	string[]	Ordered tags from the provider; the first tag supplies this Event’s tint.
timezone	string	The zone the event was saved in at its provider.
title	string	-

---

CalendarFile

Properties

Property	Type	Description
id	string | null	-
mediaType?	string | null	-
name	string	-
path	string	-
taken?	boolean	Calendar item date: true means this is the Photo’s capture date (#624).
thumb	string | null	Content hash for the Files thumbnail route when a preview is supported.
thumbnailKind?	ThumbnailKind | null	Files renderer kind for hash URLs that can refer to several previews.
time	string	HH:MM local time of the last save.

---

CalendarItemAction

One shared action label, accessible name, icon, and behavior flags. Issues #581 and #628; DESIGN §34.

Properties

Property	Type
accessibleLabel	string
destructive?	boolean
group	CalendarItemActionGroup
icon	"link" | "paperclip" | "mic" | "pencil" | "eye-off" | "copy" | "calendar" | "trash"
id	CalendarItemActionId
label	string
shortcut?	"calendar.attach" | "calendar.recordVoice" | "calendar.duplicate"

---

CalendarLog

A log entry: the record of something the user did (actual time).

Properties

Property	Type	Description
attachments	CalendarAttachment[]	-
awaitingProjection?	boolean	The server acknowledged the Log, but its Calendar projection is not indexed yet (#468).
end	string | null	-
id	string | null	The line’s ^block-id, or a temporary pending: identity before ack.
pending?	boolean	The entry is visible while its one durable Log batch is in flight (#468).
place?	{ id: string; name: string; } | null	Saved place identity and name snapshot recorded with the Log (#391, DESIGN §47).
start	string	-
tags	string[]	-
timezone?	string | null	The zone the entry was logged in, when the Index knows it.
title	string	-

---

CalendarLogPart

A rendered part of one Log entry; its data stays on sourceDate (#469).

Extends

• Omit<CalendarTimePart, "end">

Properties

Property	Type	Description	Inherited from
continuesAfter	boolean	-	CalendarTimePart.continuesAfter
continuesBefore	boolean	-	CalendarTimePart.continuesBefore
date	string	-	CalendarTimePart.date
end	string | null	A point Log has no stored end; range parts have an exclusive end.	-
log	CalendarLog	-	-
rangeEnd	number	-	-
rangeStart	number	Whole Log range, in minutes from its source day’s midnight, for drag edits.	-
sourceDate	string	-	-
start	string	-	CalendarTimePart.start

---

CalendarNote

Properties

Property	Type	Description
id	string	-
path	string	-
time	string	HH:MM local time of the last save.
title	string	-

---

CalendarSnapInput

Inputs for the shared priority resolver used by create, move, resize and keyboard nudges.

Properties

Property	Type	Description
altKey?	boolean	-
excludeKey?	string	The active item does not attract its own move or resize gesture.
gridMode?	"none" | "floor" | "round"	New-range starts preserve the existing floor behavior; none keeps keyboard step deltas.
hourPixels	number	-
itemEdges?	readonly CalendarSnapItemEdge[]	Same-day edges sorted by minute so the resolver can bound its scan.
itemIntervals?	readonly CalendarSnapItemInterval[]	Cached interval pairs keep pointer-frame create checks allocation-free (#714).
keyboardFrom?	number	Source minute for a keyboard step that must stop on crossed item edges (#714).
maxMinute?	number	Keep this at 1440 for a day edge, or extend it while resizing overnight.
minute	number	-
nowMinute?	number	-
snapInsideItem?	"after" | "before"	Clamp a create edge inside an interval to that interval’s safe boundary (#714).
snapToItems?	boolean	-
snapToNow?	boolean	-
stepMinutes	number	-

---

CalendarSnapItemEdge

One visible boundary that a Calendar drag can line up with (#536).

Properties

Property	Type
edge	"end" | "start"
key	string
minute	number

---

CalendarSnapItemInterval

A same-day item interval, prebuilt with edge candidates when Calendar data changes.

Properties

Property	Type
end	number
key	string
start	number

---

CalendarTask

Properties

Property	Type	Description
continuesAfter?	boolean	-
continuesBefore?	boolean	-
createdClock?	string | null	-
createdDate?	string | null	User-zone creation day and minute for a Task without explicit placement (#655).
dueClock?	string | null	Clock half of a timed due property, normalized to HH:MM.
dueDate?	string | null	Date half of a timed due property returned by the Task API.
id	string	-
kind?	"file" | "inline"	Only file Tasks have a stable property write route for Calendar drag edits (#536).
priority	string | null	-
readOnly?	boolean	Shared Calendar reads have no Task write authority (#655 review, DESIGN §54).
role	string	Why the Task is on this day, including one generated recurrence occurrence (#659).
scheduledClock?	string | null	Clock half of a timed scheduled property, normalized to HH:MM.
scheduledDate?	string | null	Date half of a timed scheduled property returned by the Task API.
source	string	-
startClock?	string | null	Clock half of a timed start property, normalized to HH:MM.
startDate?	string | null	Date half of a timed start property returned by the Task API.
status	string	-
tags	string[]	-
timeEnd?	string | null	Exclusive end clock for a timed task part (24:00 is day end).
timeSourceDate?	string | null	Source day that owns a multi-day timed Task.
timeStart?	string | null	Start clock for a timed task part; absent means it stays in the all-day lane.
title	string	-

---

CalendarTimePart

One half-open part of a timed item, clipped to a local Calendar day (#469).

Properties

Property	Type	Description
continuesAfter	boolean	-
continuesBefore	boolean	-
date	string	-
end	string	Exclusive end; 24:00 means the next local day’s midnight.
start	string	-

---

CalendarWindow

Properties

Property	Type
anchor	string
span	number

---

CollectionItem

What the collection needs to draw one entry.

Properties

Property	Type	Description
detail?	string	Caller-owned context: Trash origin or Shared Group (#1028).
dir	boolean	-
key	string	-
kind	FileGlyphKind	-
kindLabel	string	-
modified	string	Secondary columns, already formatted by the caller.
name	string	-
shared	boolean	-
size	string	-
thumb	string | null	-

---

ContextualBar

A page-owned capsule surface that temporarily occupies the shared bottom chrome row. offsetX moves the measured Tab Bar stage with the same spring when a card belongs in the content column beside the sidebar (#640, §45).

Properties

Property	Type	Description
component	Component<any>	-
offsetX?	string	Optional CSS length used to centre a morph card over the content column.
props?	Record<string, unknown>	-

---

CreateRange

A range selected on the hour grid for creation, in minutes after midnight.

Properties

Property	Type
date	string
end	number
start	number

---

DateTimePreferences

Properties

Property	Type
date_format	"system" | "dmy_slash_padded_short" | "mdy_slash_short" | "dmy_slash_short" | "mdy_slash_long" | "dmy_slash_padded_long" | "dmy_dot" | "dmy_dash" | "ymd_slash" | "ymd_dot" | "iso"
first_day_of_week	"system" | "sunday" | "monday" | "saturday"
time_format	"system" | "24_hour" | "12_hour"

---

DayCounts

Per-kind totals. The API sends counts beside capped item lists, and the Year payload sends counts only, so every total reads from here.

Properties

Property	Type
events	number
files	number
logs	number
notes	number
photos	number
tasks	number

---

DayRepairs

A day’s #53 diagnostics: unparsed lines plus Log heading problems.

Properties

Property	Type
duplicateHeadings	number
lines	RepairLine[]
missingHeading	boolean

---

DraggablePopoverOptions

draggablePopover: move a persistent popover freely around the screen (owner, 2026-09-25: a selected Calendar item’s popover). Apply it to the popover’s surface; it only acts while enabled is true. It lives with the shared popover primitives so every popover can take it.

• A press on a NON-text, NON-control area (the padding, the header background, empty space) starts a drag after a small movement threshold (DRAG_THRESHOLD_PX), so a click is never a drag. Text stays selectable; buttons, links, chips and fields keep working.
• Touch: a long press (LONG_PRESS_MS, still) on a non-text area, then drag; a finger that moves first is scrolling and cancels.
• The position is clamped inside the viewport (MARGIN_PX), written as left/top on the surface (the popover is position: fixed), and reported through onmove so the owner stops re-anchoring it.
• Keyboard: while the surface itself has focus, the arrow keys move it by KEY_STEP_PX (Shift: 5 × that) and onannounce('Moved') is called for a polite live region.
• The draggable areas show a grab cursor (data-draggable on the surface, styled by the owner); grabbing while a drag runs. No inertia, so reduced motion needs nothing extra.

Properties

Property	Type	Description
enabled	boolean	-
onannounce?	(message) => void	Polite announcement for a keyboard move.
onmove?	(left, top) => void	The popover moved (by pointer or keys); left/top in px.

---

EventTint

Properties

Property	Type	Description
background	string	A theme-aware soft fill from the shared tag palette or layer colour.
color	string	The tag foreground, validated layer colour or neutral marker for an untagged Event.
hover	string	Slightly stronger than the resting fill for hover.
past	string	The resting fill with a quieter category mix for past Events.
pastText	string	Past text retains readable contrast on the quiet fill.
selected	string	Stronger than hover while selected or open.
text	string	Tag-hued text or theme ink chosen to keep text readable over the fill.

---

GridItem

A standalone item on the Week and Day grid: a file, Photo, Note or bookmark saved on its own, placed at its own time and packed beside overlapping timed entries (#589). Attachments of a Log entry stay on the entry (DESIGN §39).

Properties

Property	Type	Description
at?	string	Original indexed time, used to pick the newest three deck cards.
itemId	string | null	-
kind	"note" | "file" | "photo" | "bookmark"	-
mediaType	string	-
name	string	File name, or the Note or bookmark title.
noteId	string | null	-
ownerId	string	The Home that holds the item (a Share can show another User’s items).
path	string	Home-relative path in the owner’s Home.
taken	boolean	True when this Calendar row is the capture date; false for its upload date.
thumb	string | null	Files thumb route URL for images and videos; null draws a glyph tile.
time	string	HH:MM local time: taken or added for photos, saved for the rest.
url	string | null	The page address of a bookmark.

---

HourGroup

Files or photos saved in one hour: the true count plus a few representatives.

Properties

Property	Type	Description
count	number	-
hour	number	Hour of day, 0–23.
items	CalendarFile[]	-

---

InlineAudioPlaybackState

Reactive state for the shared voice memo player. Playback helpers own its lifecycle (#622, #822; DESIGN §38).

Properties

Property	Type	Description
currentTime	number	-
duration	number	-
failed	boolean	-
key	string | null	-
playing	boolean	-
rate	number	Playback speed, kept across sounds like a podcast player.

---

InlineAudioView

What one control shows for its key: reactive when read in a template.

Properties

Property	Type	Description
active	boolean	-
currentTime	number	Seconds; 0 until the browser has decoded the length.
duration	number	-
playing	boolean	-
progress	number	0–1 share of the sound already played.

---

InteractiveSpring

Properties

Property	Modifier	Type	Description
current	readonly	number	Current position in the caller’s units.
target	readonly	number	Current target in the caller’s units.
velocity	readonly	number	Current velocity in caller-units per second.

Methods

cancel()

cancel(): void

Stop scheduling frames and preserve the current position and velocity.

Returns

void

follow()

follow(value, time?): void

Follow direct manipulation while keeping a velocity sample for release.

Parameters

Parameter	Type
value	number
time?	number

Returns

void

hold()

hold(time?): number

Stop at the current position and retain velocity for a later retarget.

Parameters

Parameter	Type
time?	number

Returns

number

retarget()

retarget(target): void

Move to a new target from the current position and velocity.

Parameters

Parameter	Type
target	number

Returns

void

---

InteractiveSpringOptions

Properties

Property	Type	Description
onRest?	(target) => void	-
reducedMotion?	() => boolean	Read the live preference so reduced motion makes every retarget immediate.
scheduler?	SpringFrameScheduler	Frame source; injectable to make the motion contract deterministic in tests.

---

ItemSlot

One activity deck on the grid. Upload-day Photos use one Added deck per day.

Properties

Property	Type	Description
added	boolean	-
first	number	The first item’s own time, minutes after midnight.
items	GridItem[]	Items of one kind close in time, or all Photos added on this date.
start	number	Start of the fixed interval, or earliest upload time for an Added deck.

---

LinkedHeadingModel

Properties

Property	Type
href	string
title	string

---

LinkedMentionRow

Properties

Property	Type	Description
copyLabel?	string	Optional Copy link action, for Canvas membership (#977, DESIGN §60).
excerpt	string | null	The referring line, or null when it could not be read.
href	string	-
key	string	-
label	string	-

---

LogEdit

Changed fields of one log entry; end: null clears the end.

Properties

Property	Type
end?	string | null
start?	string
tags?	string[]
title?	string

---

LongDateOptions

Properties

Property	Type	Description
localeOrder?	boolean	Use locale order even when the User chose a different numeric date pattern.
month?	"long" | "short"	-
timeZone?	string	-
weekday?	false | "long" | "short" | "narrow"	-
weekdaySeparator?	string	-
year?	boolean	-

---

MenuHeaderNode

Optional visible section caption. The menu keeps its icon and text columns aligned around the caption.

Properties

Property	Type
label	string
type	"header"

---

MenuItemNode

Properties

Property	Type	Description
ariaLabel?	string	Optional spoken name when an internal navigation row uses a shorter label.
checked?	boolean	-
children?	MenuNode[]	Submenu items. Presence alone makes this item open a flyout instead of firing onaction directly (Enter/Space/click open it, matching macOS).
danger?	boolean	-
detail?	string	Short status text at the trailing edge, for example “In use”.
disabled?	boolean	-
dropTarget?	boolean	Optional drop target, used by folded breadcrumb links.
fontFamily?	string	Local preview face for the label (for example, the Fonts settings menu).
icon?	string | MenuIcon	Lucide component for this action. Trusted static SVG path data remains supported for existing callers.
id	string	-
kbd?	KbdKey[]	Shortcut keys — renders a trailing Kbd AND sets aria-keyshortcuts.
label	string	-
onDragLeave?	() => void	-
onDragOver?	(event) => void	-
onDrop?	(event) => void	-
shortcut?	any	Registry shortcut — preferred when the action has a reusable binding.
swatch?	string	A validated hex colour chip in the menu’s leading glyph column.
type?	"item"	-
variant?	"default" | "radio" | "checkbox"	‘radio’/‘checkbox’ show a trailing check when selected and set the matching ARIA role; ‘default’ is a plain action.

---

MenuSeparatorNode

Properties

Property	Type
type	"separator"

---

NearPointOptions

Properties

Property	Type	Description
bounds?	object	Keep the full surface inside this visible rectangle when supplied.
bounds.bottom	number	-
bounds.left	number	-
bounds.right	number	-
bounds.top	number	-
gap?	number	Gap from the pointer to the surface (default: 8 CSS px).
margin?	number	Minimum gap from each safe-area edge (default: 8 CSS px).
vertical?	"below" | "center"	Put the surface below the pointer, or centre it on the point.
viewport?	object	Override the viewport size in non-browser callers and tests.
viewport.h	number	-
viewport.w	number	-

---

NearPointResult

Extends

• PlaceResult

Properties

Property	Type	Description	Inherited from
availableWidth	number	Maximum width that keeps the selected side clear of the point.	-
left	number	-	PlaceResult.left
placement	"up" | "down"	The direction in which the element actually opened: ‘down’ — below the anchor (normal case) ‘up’ — above the anchor (flipped because the bottom edge was too close)	PlaceResult.placement
side	"left" | "right"	Horizontal side selected after checking available room.	-
top	number	-	PlaceResult.top

---

NoteProperty

Properties

Property	Type
key	string
value	string

---

PageChrome

Properties

Property	Type	Description
actions?	PageChromeAction[]	-
back?	object	A nested page’s parent action, shown in the leading header slot.
back.label	string	-
back.onaction	() => void	-
breadcrumbs?	PageChromeBreadcrumb[]	Visible path segments. Every segment remains a deep link.
canDropBreadcrumb?	(path, event) => boolean	Drop handlers for shared file targets in the visible breadcrumb row.
center?	Snippet<[PageChromeContext]>	A control group centred between the title and the page actions.
contextualBar?	ContextualBar	A selection or editing bar that replaces the bottom capsule.
copyLink?	object	The current view’s stable URL, rendered with the shared CopyLink control.
copyLink.href	string	-
copyLink.label	string	-
copyLink.shortcut?	any	-
inlineTitle?	boolean	The page’s large title is in its content; the compact header title dissolves in as it passes under the progressive blur.
morphCard?	ContextualBar	A page surface that expands the Tab Bar capsule over the current view.
onaction	(id, anchor?) => void | Promise<void>	-
onbreadcrumbdrop?	(path, event) => void	-
onprimaryshortcut?	() => void	Run or open the primary action when page chrome replaces the pill (#1128).
onviewmode?	(id) => void	-
overflow?	MenuNode[]	-
primary?	PageChromeAction	The mode’s primary action: the pill beside the mode tray.
title?	string	The header title; omit to keep the sub-view name.
titleContent?	Snippet<[]>	Draws the title (for example with a morph); title stays its name.
tools?	Snippet<[PageChromeContext]>	-
viewMode?	string	-
viewModes?	PageChromeViewMode[]	A page’s adjacent view choices, shown in one shared PillGroup capsule.

---

PageChromeAction

Properties

Property	Type	Description
contextMenu?	MenuNode[]	Secondary actions shown by right-click or touch long-press on the primary action.
disabled?	boolean	-
expanded?	boolean	aria-expanded for an action that toggles a popover (the Inspector).
icon	IconComponent	-
id	string	-
label	string	-
menu?	MenuNode[]	-
popup?	"dialog" | "menu"	aria-haspopup for an action that opens a dialog (the Inspector).
shortcut?	any	-

---

PageChromeContext

The size context that page-owned center and tools snippets render in.

Properties

Property	Type	Description
compact	boolean	A narrow row: page tools should collapse secondary controls into one action.
phone	boolean	A phone-width row: controls that do not fit can collapse.

---

PageChromeViewMode

One view choice in the contextual Top row capsule (DESIGN §34, #582).

Properties

Property	Type
icon	IconComponent
id	string
label	string

---

Placed

Type Parameters

Type Parameter
T

Properties

Property	Type	Description
cluster?	number	The overlap cluster (a run of items that overlap in time), numbered in time order.
column	number	Column inside its overlap cluster and the cluster’s column count.
columns	number	-
end	number	-
item	T	-
layoutEnd	number	End used for overlap packing when the rendered card needs a title-line floor (#384).
layoutStart	number	Start used for a short visual floor when it grows upward at midnight (#384, #469).
point	boolean	-
start	number	-

---

PlaceOptions

Properties

Property	Type	Description
align?	HAlign	Horizontal alignment of the floating element relative to anchor.x. ‘left’ (default) — anchor.x is the natural left edge of the element. ‘right’ — anchor.x is the natural left edge of a right-aligned element (e.g. buttonRight − menuWidth). The clamping logic is identical in both cases; this is a semantic label for callers.
bounds?	object	Visible clipping band in viewport coordinates. When provided, placement is clamped to this band instead of the whole window. This is the shared edge-aware path for floating UI inside a scroll container: callers pass the intersection of the container and the browser viewport.
bounds.bottom	number	-
bounds.left	number	-
bounds.right	number	-
bounds.top	number	-
flipY?	number	The hinge for an upward flip: the element’s BOTTOM edge when it opens up (default: anchor.y, the same pixel as the downward hinge). A caller that anchors to a trigger ELEMENT passes trigger.top − gap here, so a flipped menu sits above the trigger instead of covering it (see anchorToRect).
margin?	number	Minimum safe gap from every viewport edge in CSS px (default: 8).
preferUp?	boolean	Force upward placement regardless of available space below (default: false). Useful when the trigger is known to sit near the bottom of the screen.
viewport?	object	Override viewport dimensions (default: window.innerWidth / innerHeight). Useful for unit tests that run outside a browser environment.
viewport.h	number	-
viewport.w	number	-

---

PlaceResult

Extended by

• NearPointResult

Properties

Property	Type	Description
left	number	-
placement	"up" | "down"	The direction in which the element actually opened: ‘down’ — below the anchor (normal case) ‘up’ — above the anchor (flipped because the bottom edge was too close)
top	number	-

---

PullDownOpts

Properties

Property	Type	Description
allowAwayFromTop?	boolean	Explicitly allow this registered surface to arm away from document top. Defaults to false so every existing pullDown caller keeps top-only behavior.
bandPx?	() => number	Optional TOP-BAND arming: when set, a downward pry ALSO arms if the pointer started within bandPx() of the viewport top — even when the feed is scrolled down. This is what lets a pull-down originating in the date-strip band open the palette mid-feed (refine-2). Without it, only the scroll-top pull arms.
canPull?	() => boolean	are we allowed to pull at all? When false the pull is ignored entirely. Defaults to always-allowed; this is an early bail, not the only guard.
isBusy?	() => boolean	true while the action’s target is already open/busy — pulls become a no-op (don’t re-trigger). The consumer wires this to e.g. paletteOpen.
maxPull?	number	max indicator travel (px) the rubber-band asymptotes toward
oncancel?	() => void	drag ended/aborted without committing (snap back to 0)
oncommit?	(outcome) => void | Promise<void>	released with a non-cancel outcome. Awaited so the action can hold the indicator until it settles.
onmove?	(offset) => void	live indicator offset while dragging (px, ≥0)
onstart?	() => boolean | void	Reserve shared ownership once downward vertical intent wins. Returning false rejects this pointer without claiming or preventing its movement.
reduced?	() => boolean	true to skip the elastic curve + clamp linearly (prefers-reduced-motion)
resolveOutcome?	(offset) => PullActionOutcome	optionally resolves a release to one of multiple actions; when omitted, pullDown keeps its legacy single-threshold refresh behavior.
scrollTop?	() => number	scroll position getter — a pull always arms when this is ~0 (at the very top). Defaults to the app route feed (#718), then Window for other hosts.
threshold?	number	indicator offset (px) at which a release commits
tolerance?	number	dead zone (px) before a vertical drag is treated as a pull

---

RectAnchor

A trigger-anchored placement request (see anchorToRect).

Properties

Property	Type	Description
flipY	number	Upward hinge (PlaceOptions.flipY): gap px above the trigger’s top edge.
originX	number	The trigger’s horizontal centre — where the surface’s transform-origin goes.
x	number	Horizontal hinge: the trigger’s left edge (‘left’) or right edge (‘right’).
y	number	Downward hinge: gap px below the trigger’s bottom edge.

---

RepairLine

An unparsed line inside a day’s Log section, with an optional fix (#53).

Properties

Property	Type
hash	string
raw	string
suggestion	string | null

---

ResizableEdgeOptions

resizableEdge: make a side panel resizable by dragging its edge (owner rule in CLAUDE.md, issue #66). Apply it to an empty element that straddles the panel edge; the action turns that element into the invisible hit zone.

• No visible handle. The zone is transparent, ~8 px wide, with a col-resize cursor. Nothing is drawn at rest, on hover or while dragging (the owner rejected invented borders).
• Live resize runs on requestAnimationFrame and writes ONE custom property (--<id>-width) on the target element, so the drag never forces layout from script and a frame never repeats work.
• Min/max clamp; dragging below min - snap snaps the panel collapsed. Reopening restores the last width (the caller shows the panel again and the stored width is still there).
• Double-click resets to the default width.
• Keyboard and assistive tech: role="separator", aria-orientation, aria-valuenow/min/max; ←/→ resize by step, Shift for 4 × step, Home/End jump to min/max, Enter collapses.
• Persistence: the width is stored per panel under calternal.panel.<id> in this Installation’s local storage. This action does not send widths to the server. readPanelWidth lets a layout apply the stored width before first paint, so there is no layout shift on load.
• Coarse pointers (phones) do not get the zone: there the panels are sheets. Tablets with a fine-enough pointer still resize.

Properties

Property	Type	Description
edge	"end" | "start"	Which edge of the panel the zone sits on. end = right edge of a left panel (the sidebar); start = left edge of a right panel.
id	string	Stable panel ID; names the CSS property and the storage key.
initial	number	Default width in px; double-click restores it.
label	string	Accessible name, e.g. “Resize sidebar”.
max	number	-
min	number	-
onchange?	(width) => void	Called after every committed width (drag end, key, reset).
oncollapse?	() => void	Called when a drag or Enter collapses the panel. Omit to disable snap-to-collapse.
snap?	number	How far below min a drag must go to collapse. Default 48 px.
step?	number	Keyboard step in px. Default 16.
target	() => HTMLElement | null	Element that receives the --<id>-width custom property.

---

SegmentedOption

Properties

Property	Type	Description
ariaLabel?	string	Accessible name; falls back to label when omitted.
disabled?	boolean	A disabled member. TAB semantics: focusable-but-disabled (the Tasks tab). It announces (aria-disabled), stays focusable, and on activation ALWAYS calls onblocked — never the re-pick no-op. RADIO semantics: an unavailable choice (the composer’s Event/Task modes while it is bound to an event’s “Add note”). It announces aria-disabled, recedes visually, is never tabbable, is skipped by arrow/Home/End selection, and ignores activation. A disabled radio is never the selected value in practice; the consumer keeps value on an enabled option.
icon?	string	SVG path d (e.g. from modeGlyphs) → renders a decorative glyph. When set, the label is icons-only unless showLabels.
id	string	-
label	string	-
modeIconId?	string	Shared Tab artwork when this option represents an app Tab (#1095–#1097).
tooltip?	object	The warm tooltip for this option (DESIGN §34), with its shortcut.
tooltip.icon?	TooltipIconName	-
tooltip.label	string	-
tooltip.shortcut?	any	-

---

SelectionBarAction

Properties

Property	Type
disabled?	boolean
href?	string
icon	Component
id	string
label	string
shortcut?	any

---

SelectOption

Properties

Property	Type
disabled?	boolean
label	string
value	string

---

SolarBoundary

Properties

Property	Type
at	number
darkAfter	boolean
kind	"sunrise" | "sunset"

---

SolarCoordinates

Properties

Property	Type
latitude	number
longitude	number

---

SolarEvents

Properties

Property	Type	Description
polarState	"day" | "night" | null	Solar state at local noon when the date has no sunrise or sunset.
sunrise	number | null	UTC epoch milliseconds, or null during the corresponding polar season.
sunset	number | null	UTC epoch milliseconds, or null during the corresponding polar season.

---

SpringFrameScheduler

Methods

cancel()

cancel(id): void

Parameters

Parameter	Type
id	number

Returns

void

now()

now(): number

Returns

number

request()

request(callback): number

Parameters

Parameter	Type
callback	FrameRequestCallback

Returns

number

---

StripCell

A single cell in the date strip.

Properties

Property	Type	Description
date	string	YYYY-MM-DD
day	number	day-of-month, e.g. 23
dow	string	single-letter weekday initial, locale-aware, e.g. “M”
isToday	boolean	true if this is the device’s today
week	number	ISO week number this date falls in (1..53). The “W38” blob shows the ISO number on purpose: ISO numbering is a fixed, shared standard (it matches calendars and work planning tools), while where a week STARTS follows the locale (weekStart below).
weekStart	boolean	true if this date is the first day of its LOCALE week (lib/weekStart.ts: Sunday in the US, Monday in GB/DE, …) — used for subtle week-boundary separators in the strip.

---

SwipeOpts

Properties

Property	Type	Description
enabled?	() => boolean	Backward-compatible alias for pointerSwipeEnabled. It only gates pointer swipe ownership; long press and wheel ownership remain independent.
leftThreshold?	number	px of travel to commit a LEFT swipe; defaults to threshold. Make this larger for a destructive left action so it’s hard to trigger by accident.
longPressMs?	number	-
moveTolerance?	number	movement (px) that cancels a long-press
oncancel?	() => void	drag ended without committing (snap back)
onlongpress?	(x, y) => void	long-press fired (ms held without moving)
onLongPressClaim?	() => void	App-specific protection when a long press opens a menu over selectable text.
onmove?	(dx) => void	live drag offset (px, signed)
onswipe?	(dir) => void	committed swipe in a direction
pointerSwipeEnabled?	() => boolean	Dynamic gate for pointer swipe ownership. Long-press/context-menu handling remains available when this is false, and wheel ownership is controlled by wheelEnabled independently. Defaults true so every existing caller preserves its current behavior.
pointerTypes?	("touch" | "pen" | "mouse")[]	#27 B §C.1 — restrict which pointer types can ARM this gesture (default: all — the original behavior, unchanged for every pre-existing caller). The composer’s in-input swipe passes ['touch', 'pen']: on desktop a horizontal MOUSE drag inside a textarea is ordinary text selection and must stay text selection — hijacking it as a stack/discard swipe would break click-drag-to-select. Desktop gets the keyboard + named a11y actions instead (§C.2/§C.3), never the gesture.
selectionEl?	() => { selectionEnd: number | null; selectionStart: number | null; } | null	#27 B §C.1 — selection/caret guard (feasibility finding). When set, the gesture arms ONLY if this element’s selection is COLLAPSED at pointerdown (selectionStart === selectionEnd) — a drag starting on selected text / a caret handle is real iOS Safari behavior starting a native text-selection drag, never a stack/discard swipe. While armed we also watch selectionchange: if the selection un-collapses MID-drag (WebKit can start a selection a few px into an already-armed gesture — the pointerdown check alone isn’t a complete guard), the gesture aborts as a cancel — snap back, never commit a swipe. A getter (not a plain value) so a caller can pass a live ref to a textarea that may not exist yet at mount time (e.g. Composer’s () => textarea). Additive to pointerTypes above, not a replacement for it.
shouldStart?	(target) => boolean	Keep controls, editors and nested gesture owners outside this action.
threshold?	number	px of travel to commit a RIGHT swipe (and the default for both)
wheelBurstKey?	string	Stable owner key for a discrete pager whose DOM node can remount during a wheel burst. The key suppresses trailing horizontal packets until idle.
wheelDominance?	number	Horizontal-to-vertical ratio required to lock a wheel sequence to x.
wheelEnabled?	boolean | (() => boolean)	Opt-in horizontal mouse/trackpad wheel recognition. It is deliberately false by default: text inputs and other existing swipe surfaces must not start reacting to wheel input until their owner explicitly opts in. The wheel listener is attached ONLY while this resolves true, evaluated at mount and on every action update(). A non-passive wheel listener makes the compositor wait for the main thread before it scrolls over the node, so a feed of cards must not pay that cost while the setting is off. Pass a plain boolean from a Svelte template (for example wheelEnabled: settings.trackpadSwipes) so a setting change re-runs update(). A getter is still honoured per event, but a getter that turns true after mount only takes effect on the next update().
wheelIdleMs?	number	Inactivity window after the last wheel event that ends a sequence.
wheelThreshold?	number	Minimum accumulated normalized wheel travel for a commit. Defaults to the direction-specific pointer threshold when omitted.
wheelTolerance?	number	Accumulated wheel travel dead zone before axis lock.

---

ThemeDef

Properties

Property	Type	Description
dark	boolean	-
group	ThemeGroup	-
id	ThemeId	-
label	string	-
swatch	string	Representative swatch from this palette’s accent.

---

ThemeFamilyDef

Properties

Property	Type	Description
dark	ThemeId	-
darkVariants?	readonly ThemeId[]	Alternate dark palettes; this curated set has no alternate light palettes.
id	ThemeFamilyId	-
label	string	-
light	ThemeId	-

---

TimezoneCity

Properties

Property	Type
city	string
latitude	number
longitude	number

---

TooltipAttributes

Properties

Property	Type
aria-keyshortcuts?	string
data-tooltip	string
data-tooltip-fallback?	string
data-tooltip-icon?	TooltipIconName
data-tooltip-keys?	string
data-tooltip-side?	"top" | "bottom"

---

UnlinkedMentionRow

Properties

Property	Type
excerpt	object
excerpt.after	string
excerpt.before	string
excerpt.match	string
href	string
key	string
label	string

---

ViewerItem

Properties

Property	Type	Description
badge?	string | null	A short badge after the name (“RAW”, “LIVE”, “5”).
decodable?	boolean	The browser can decode src as an image.
download?	string | null	Download URL; omitted when the viewer may not download.
downloadName?	string	Original file name for the download when name is a friendly display title.
headers?	Record<string, string>	Request headers for fetches (public link password).
hls?	string | null	Video: an HLS playlist to fall back to when direct play fails.
key	string	-
kind	FileGlyphKind	-
link?	string | null	In-app deep link (/f/<id>); enables Copy link.
meta?	string	One line under the name: size · modified.
motion?	string | null	Live Photo: the motion clip, played on hover or press.
name	string	-
preview?	string | null	Fast preview (server thumbnail); shown first, and alone for RAW/HEIC.
src	string | null	Inline URL for the bytes (image, PDF, media, text).

---

WheelDelta

A normalized wheel delta. WheelEvent.deltaMode can report pixels, lines or pages depending on the input device and browser, so wheel gesture decisions must use one unit before accumulating a sequence.

Properties

Property	Type
x	number
y	number

Type Aliases

ActivityKind

ActivityKind = "notes" | "files" | "photos"

---

AgendaList

AgendaList = ReturnType<typeof AgendaList>

---

AttachmentDeck

AttachmentDeck = ReturnType<typeof AttachmentDeck>

---

AttachmentFamily

AttachmentFamily = "image" | "video" | "audio" | "voice-memo" | "archive" | "document" | "other"

---

Axis

Axis = "x" | "y"

---

CalendarActionItem

CalendarActionItem = Extract<PreviewItem, { kind: "log" | "event" | "task"; }>

A Log entry, Event, or Task preview that can have Calendar item actions (#581, #628; DESIGN §34).

---

CalendarItemActionAvailability

CalendarItemActionAvailability = Partial<Record<CalendarItemActionId, boolean>>

Availability flags for Calendar actions; an omitted or false flag hides that action (#581, #628; DESIGN §34).

---

CalendarItemActionGroup

CalendarItemActionGroup = "title" | "leading" | "trailing"

The action position in a preview or context menu: title, leading, or trailing. Issues #581 and #628; DESIGN §34.

---

CalendarItemActionId

CalendarItemActionId = "copy-link" | "attach-file" | "voice-memo" | "edit" | "hide" | "duplicate" | "copy-to-calendar" | "delete"

Stable IDs for actions in Calendar item previews and context menus. Issues #581 and #628; DESIGN §34.

---

CalendarPlanMoveMode

CalendarPlanMoveMode = "move" | "resize-start" | "resize-end"

Pointer edit mode for a timed Calendar item (#536).

---

CalendarPopover

CalendarPopover = ReturnType<typeof CalendarPopover>

---

CalendarSnapTarget

CalendarSnapTarget = { edge: "start" | "end"; key: string; kind: "item"; } | { kind: "now"; } | { kind: "grid"; } | { kind: "free"; }

The magnetic target currently controlling a drag preview.

---

CalendarTimedPlan

CalendarTimedPlan = { continuesAfter?: boolean; continuesBefore?: boolean; date: string; end: string | null; event: CalendarEvent; kind: "event"; start: string; } | { continuesAfter?: boolean; continuesBefore?: boolean; date: string; end: string | null; kind: "task"; start: string; task: CalendarTask; }

The Event or Task interval drawn in one timed Calendar day column (#536).

---

CalendarTimeStep

CalendarTimeStep = typeof CALENDAR_TIME_STEPS[number]

---

CalendarTitle

CalendarTitle = ReturnType<typeof CalendarTitle>

---

CalendarTools

CalendarTools = ReturnType<typeof CalendarTools>

---

CalendarView

CalendarView = "today" | "day" | "week" | "month" | "year"

---

Card

Card = ReturnType<typeof Card>

Public exports for the shared UI package; request states, picker scheme types and their contracts stay beside shared controls (#506, #869, DESIGN §35).

---

Checkbox

Checkbox = ReturnType<typeof Checkbox>

---

CheckboxMode

CheckboxMode = "control" | "input" | "mark"

---

CheckboxState

CheckboxState = "none" | "some" | "all"

State and rendering modes for the shared Checkbox, including the indeterminate state (#406, DESIGN §35).

---

CheckboxVariant

CheckboxVariant = "file" | "tile" | "form" | "editor" | "photo" | "menu"

---

ChromeActions

ChromeActions = ReturnType<typeof ChromeActions>

---

CollectionSortKey

CollectionSortKey = "name" | "kind" | "size" | "modified"

---

CollectionView

CollectionView = "list" | "grid"

---

ComposerModeId

ComposerModeId = keyof typeof COMPOSER_MODE_GLYPHS

---

ComposerModePill

ComposerModePill = ReturnType<typeof ComposerModePill>

---

CopyableValue

CopyableValue = ReturnType<typeof CopyableValue>

Make a displayed value a copy control. value is copied in full; displayValue changes only the visible text. Keep secrets out of label, which forms the accessible name. Issue #723.

---

CopyLink

CopyLink = ReturnType<typeof CopyLink>

---

CopyLinkVariant

CopyLinkVariant = "pill" | "segment" | "menu-item" | "value"

---

DateFormat

DateFormat = typeof DATE_FORMATS[number]

---

DateStrip

DateStrip = ReturnType<typeof DateStrip>

---

Disclosure

Disclosure = ReturnType<typeof Disclosure>

---

DraftStack

DraftStack = ReturnType<typeof DraftStack>

---

Fab

Fab = ReturnType<typeof Fab>

---

FieldPopover

FieldPopover = ReturnType<typeof FieldPopover>

---

FileCollection

FileCollection = ReturnType<typeof FileCollection>

---

FileGlyphKind

FileGlyphKind = "folder" | "image" | "pdf" | "video" | "audio" | "voice-memo" | "markdown" | "code" | "text" | "archive" | "other"

---

FileName

FileName = ReturnType<typeof FileName>

---

FileThumb

FileThumb = ReturnType<typeof FileThumb>

---

FirstDayOfWeek

FirstDayOfWeek = typeof FIRST_DAY_CHOICES[number]

---

FloatingSidebar

FloatingSidebar = ReturnType<typeof FloatingSidebar>

---

FloatingSurface

FloatingSurface = ReturnType<typeof FloatingSurface>

---

HAlign

HAlign = "left" | "right"

Horizontal alignment hint provided by the caller.

---

HighlightOverlay

HighlightOverlay = ReturnType<typeof HighlightOverlay>

---

IconLabel

IconLabel = ReturnType<typeof IconLabel>

---

InlineRename

InlineRename = ReturnType<typeof InlineRename>

Let a User edit a name in place. Bind value and set textAlignment to match the static name. The caller must save or cancel the edit. Issue #1017; DESIGN §34.

---

Inspector

Inspector = ReturnType<typeof Inspector>

---

InspectorRow

InspectorRow = ReturnType<typeof InspectorRow>

Add one label and value to InspectorSection. The label appears as dt; put the value in the child snippet. Issue #659; DESIGN §34.

---

InspectorSection

InspectorSection = ReturnType<typeof InspectorSection>

Group Inspector content under a named heading. By default, children go inside a description list. Set rows to false for content such as loading or error text. busy sets aria-busy. Issue #659; DESIGN §34.

---

ItemCard

ItemCard = ReturnType<typeof ItemCard>

Show a non-interactive summary for an item. Set kind and title; optional text and media come from props. The host owns selection and actions. size controls the layout. Issue #822; DESIGN §§38–39.

---

ItemPreview

ItemPreview = ReturnType<typeof ItemPreview>

---

Kbd

Kbd = ReturnType<typeof Kbd>

---

LinkedHeading

LinkedHeading = ReturnType<typeof LinkedHeading>

---

LinkedHeadingLevel

LinkedHeadingLevel = 1 | 2 | 3 | 4 | 5 | 6

---

LogEntryEditor

LogEntryEditor = ReturnType<typeof LogEntryEditor>

---

MentionLoadState

MentionLoadState = "loading" | "ready" | "error"

---

Menu

Menu = ReturnType<typeof Menu>

---

MenuNode

MenuNode = MenuItemNode | MenuSeparatorNode | MenuHeaderNode

---

MiniMonth

MiniMonth = ReturnType<typeof MiniMonth>

---

ModeHeader

ModeHeader = ReturnType<typeof ModeHeader>

---

ModeIcon

ModeIcon = ReturnType<typeof ModeIcon>

Show the decorative glyph for a Tab. Set modeId to the Tab ID. The Calendar glyph also shows the current day and updates when that day changes. Issues #1095–#1097; DESIGN §34.

---

MonthGrid

MonthGrid = ReturnType<typeof MonthGrid>

---

NoteMentionsCard

NoteMentionsCard = ReturnType<typeof NoteMentionsCard>

---

NoteProperties

NoteProperties = ReturnType<typeof NoteProperties>

---

OverlaySurface

OverlaySurface = ReturnType<typeof OverlaySurface>

---

Pill

Pill = ReturnType<typeof Pill>

---

PillGroup

PillGroup = ReturnType<typeof PillGroup>

---

PopoverSurface

PopoverSurface = ReturnType<typeof PopoverSurface>

---

PreviewItem

PreviewItem = { date: string; kind: "log"; log: CalendarLog; } | { date: string; kind: "task"; task: CalendarTask; } | { date: string; event: CalendarEvent; kind: "event"; } | { date: string; kind: "stack"; stack: ActivityStack; } | { date: string; end: number; items: GridItem[]; kind: "items"; start: number; }

What a popover previews: one timed item, an activity deck or a summary stack.

---

PrimaryPill

PrimaryPill = ReturnType<typeof PrimaryPill>

---

ProgressiveBlur

ProgressiveBlur = ReturnType<typeof ProgressiveBlur>

---

PullAction

PullAction = "refresh" | "update"

---

PullActionOutcome

PullActionOutcome = { kind: PullAction; } | { kind: "cancel"; }

---

PullOutcome

PullOutcome = { kind: "refresh"; } | { kind: "cancel"; }

---

QuickLook

QuickLook = ReturnType<typeof QuickLook>

---

RepairList

RepairList = ReturnType<typeof RepairList>

---

RequestState

RequestState = ReturnType<typeof RequestState>

Show the loading or error state for a request. Retry appears only when both its label and callback are set. Use variant="card" for the shared page Card treatment. Issue #869; DESIGN §34.

---

SegmentedControl

SegmentedControl = ReturnType<typeof SegmentedControl>

---

Select

Select = ReturnType<typeof Select>

---

SelectionBar

SelectionBar = ReturnType<typeof SelectionBar>

---

SettingRow

SettingRow = ReturnType<typeof SettingRow>

---

SidebarSectionHeader

SidebarSectionHeader = ReturnType<typeof SidebarSectionHeader>

---

StatusPill

StatusPill = ReturnType<typeof StatusPill>

---

SwipeOutcome

SwipeOutcome = { dir: "left" | "right"; kind: "swipe"; } | { kind: "cancel"; } | { kind: "none"; }

---

TabBar

TabBar = ReturnType<typeof TabBar>

---

TagPill

TagPill = ReturnType<typeof TagPill>

---

TextInput

TextInput = ReturnType<typeof TextInput>

Show a text field with shared colours and focus styling. Bind value; other native input attributes pass through to the field. Issue #407; DESIGN §3.

---

TextView

TextView = ReturnType<typeof TextView>

---

ThemeFamilyId

ThemeFamilyId = "paper" | "meridian" | "bloom" | "mono" | "solarized" | "catppuccin" | "rose-pine" | "ayu" | "github" | "one" | "tokyo-night" | "gruvbox" | "everforest" | "kanagawa" | "dracula" | "nord"

---

ThemeGroup

ThemeGroup = "Light" | "Dark" | "Mono"

---

ThemeId

ThemeId = "paper" | "meridian" | "bloom" | "latte" | "solarized" | "solarized-dark" | "rose-pine-dawn" | "mono" | "midnight" | "ember" | "forest" | "tokyo-night-day" | "tokyo-night" | "gruvbox-light" | "gruvbox" | "frappe" | "macchiato" | "mocha" | "noir" | "one-light" | "ayu-light" | "github-light" | "nord-light" | "nord" | "alucard" | "dracula" | "one-dark" | "everforest-light" | "everforest" | "kanagawa-lotus" | "kanagawa" | "rose-pine" | "rose-pine-moon" | "ayu-dark" | "ayu-mirage" | "github-dark"

---

ThemePicker

ThemePicker = ReturnType<typeof ThemePicker>

---

ThemeSchemePreference

ThemeSchemePreference = "auto" | "system" | "light" | "dark"

Saved colour scheme choices; Auto and System can resolve to either active scheme.

---

ThemeVariantSelections

ThemeVariantSelections = Record<VariantFamilyId, ThemeId>

---

ThumbnailKind

ThumbnailKind = "media" | "pdf" | "text-card"

Renderer families used by the Files thumbnail cache (#510/#547).

---

TimeFormat

TimeFormat = typeof TIME_FORMATS[number]

---

TimeGrid

TimeGrid = ReturnType<typeof TimeGrid>

---

TimeZoneChip

TimeZoneChip = ReturnType<typeof TimeZoneChip>

Show a time zone beside a Calendar time. The chip stays hidden when the zone matches userZone. If userZone is omitted, the User’s system time zone is used for comparison. DESIGN §29 C12 and §34 (Calendar preview).

---

TodayButton

TodayButton = ReturnType<typeof TodayButton>

---

Toggle

Toggle = ReturnType<typeof Toggle>

---

TooltipIconName

TooltipIconName = "list" | "calendar-days" | "columns-3" | "grid-3x3" | "calendar-range"

---

TooltipLayer

TooltipLayer = ReturnType<typeof TooltipLayer>

---

TooltipShortcut

TooltipShortcut = FileIcon | readonly FileIcon[]

A registry shortcut id, or a raw combo for a key not in the registry.

---

UIHeading

UIHeading = ReturnType<typeof UIHeading>

---

VariantFamilyId

VariantFamilyId = "catppuccin" | "rose-pine" | "ayu"

---

VoicePill

VoicePill = ReturnType<typeof VoicePill>

Show idle, requesting, recording, or error controls for a voice memo. The caller manages capture, saving, discard confirmation, and Undo. Issue #617; DESIGN §38.

---

VoicePillState

VoicePillState = "idle" | "requesting" | "recording" | "attach-error" | "error"

States shown by VoicePill; the host owns transitions and recording data. Issue #617; DESIGN §38.

---

VoicePlayback

VoicePlayback = ReturnType<typeof VoicePlayback>

Play a voice memo with seek and speed controls. Use the same stable key as compact controls so all surfaces share one playback state. If omitted, src is the key. Issues #617, #622, #822; DESIGN §38.

---

VoicePlayToggle

VoicePlayToggle = ReturnType<typeof VoicePlayToggle>

Show the shared play or pause button for a voice memo row. The host handles onplay because it can resolve the audio source. Use the same key as VoicePlayback. The button stops clicks from reaching its row. Issue #822; DESIGN §38.

---

VoiceRecordingPill

VoiceRecordingPill = ReturnType<typeof VoiceRecordingPill>

Show recording controls for Composer or Calendar. The caller manages microphone access and saving. This component manages focus and asks for confirmation before Escape discards an active recording. Issue #619; DESIGN §34.

---

WeekDay

WeekDay = 0 | 1 | 2 | 3 | 4 | 5 | 6

First day of the week: 0 = Sunday … 6 = Saturday.

---

YearHeatmap

YearHeatmap = ReturnType<typeof YearHeatmap>

Variables

ACTIVITY_DECK_MAX_SIZE

const ACTIVITY_DECK_MAX_SIZE: 160 = 160

Maximum Activity thumbnail edge; 160 px keeps Day decks visible without taking over the lane (#589).

---

ACTIVITY_KINDS

const ACTIVITY_KINDS: readonly ActivityKind[]

---

AGENDA_INITIAL_DAYS

const AGENDA_INITIAL_DAYS: 2 = 2

Today fetches and immediately mounts this many days; older days page in. The adapter, preloader and Agenda share this bound to avoid extra work (#549).

---

AgendaList

const AgendaList: Component

---

AttachmentDeck

const AttachmentDeck: Component

---

CALENDAR_TIME_STEPS

const CALENDAR_TIME_STEPS: readonly [5, 10, 15, 30]

Supported grid increments for pointer and keyboard Calendar edits (#536).

---

CALENDAR_VIEW_OPTIONS

const CALENDAR_VIEW_OPTIONS: readonly object[]

---

CALENDAR_VIEWS

const CALENDAR_VIEWS: readonly CalendarView[]

---

CalendarPopover

const CalendarPopover: Component

---

CalendarTitle

const CalendarTitle: Component

---

CalendarTools

const CalendarTools: Component

---

CAPSULE_MOTION

const CAPSULE_MOTION: object

Kept as a descriptive alias for capsule components and existing callers.

Type Declaration

Name	Type
cap	500
countRoll	180
dampingRatio	1.08
easeOutQuint	string
exitFade	120
firstItemDelay	90
itemOffset	12
itemRise	310
itemStagger	25
maxStaggerIndex	4
morph	200

---

capsuleItemDelay

const capsuleItemDelay: typeof cascadeItemDelay

Capsule-specific name retained for the toolbar and shortcut-card callers.

---

capsuleItemTransition

const capsuleItemTransition: typeof cascadeItemTransition

---

capsuleOverdamped

const capsuleOverdamped: typeof cascadeOverdamped

---

Card

const Card: Component

Public exports for the shared UI package; request states, picker scheme types and their contracts stay beside shared controls (#506, #869, DESIGN §35).

---

Checkbox

const Checkbox: Component

---

ChromeActions

const ChromeActions: Component

---

CLOCK_LANE_MINIMUM_WIDTH

const CLOCK_LANE_MINIMUM_WIDTH: 96 = 96

Minimum width that keeps a complete Calendar time range readable (#969).

---

COLD_DELAY_MS

const COLD_DELAY_MS: 500 = 500

First tooltip after a cool-down: long enough that a passing pointer does not flash tooltips, short enough to feel like help, not like a wait.

---

COMPOSER_MODE_GLYPHS

const COMPOSER_MODE_GLYPHS: object

Type Declaration

Name	Type	Description
event	"M8 2v4M16 2v4M3 10h18M5 6h14a2 2 0 0 1 2 2v11a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2z"	An Event: a calendar page (a planned time).
log	"M12 7v5l3 2M21 12a9 9 0 1 1-18 0 9 9 0 0 1 18 0z"	A Log entry: a clock face (something done at a time).
note	"M4 4h16v12l-6 4H4z M14 20v-4h4"	-
task	"M9 11l3 3 8-8M21 12v7a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h11"	-

---

COMPOSER_MODE_LABELS

const COMPOSER_MODE_LABELS: Record<ComposerModeId, string>

---

ComposerModePill

const ComposerModePill: Component

---

COPY_FEEDBACK_MS

const COPY_FEEDBACK_MS: 500 = 500

How long the check glyph stays after a successful copy. calternal.js DateDivider’s day-copy value; CopyLink and CopyableValue share it.

---

CopyableValue

const CopyableValue: Component

Make a displayed value a copy control. value is copied in full; displayValue changes only the visible text. Keep secrets out of label, which forms the accessible name. Issue #723.

---

CopyLink

const CopyLink: Component

---

DATE_FORMATS

const DATE_FORMATS: readonly ["system", "dmy_slash_padded_short", "mdy_slash_short", "dmy_slash_short", "mdy_slash_long", "dmy_slash_padded_long", "dmy_dot", "dmy_dash", "ymd_slash", "ymd_dot", "iso"]

---

DATE_TIME_SEPARATOR

const DATE_TIME_SEPARATOR: " · " = “ \u00B7 “

The one separator between a date and its clock in compact item labels (“Sun, 4 Oct · 09:30”). Callers join through formatItemDateTime instead of writing the dot in a template, where Svelte can drop the leading space.

---

DateStrip

const DateStrip: Component

---

DEFAULT_DARK

const DEFAULT_DARK: ThemeId

First-use system defaults keep the current monochrome light/dark pair.

---

DEFAULT_DATE_TIME_PREFERENCES

const DEFAULT_DATE_TIME_PREFERENCES: DateTimePreferences

---

DEFAULT_FAMILY

const DEFAULT_FAMILY: ThemeFamilyId

---

DEFAULT_HOUR_HEIGHT

const DEFAULT_HOUR_HEIGHT: 48 = 48

---

DEFAULT_LIGHT

const DEFAULT_LIGHT: ThemeId

---

DEFAULT_THEME

const DEFAULT_THEME: ThemeId

---

DEFAULT_VARIANTS

const DEFAULT_VARIANTS: ThemeVariantSelections

---

Disclosure

const Disclosure: Component

---

DraftStack

const DraftStack: Component

---

DUR

const DUR: object

Shared durations in seconds for Motion’s JavaScript API. These roles keep the existing CSS timings exact while letting new CSS use the same tokens.

Type Declaration

Name	Type
ambient	1.4
brief	0.14
close	0.12
fast	0.1
feedback	0.3
highlight	1.2
instant	0.000001
long	0.22
longAmbient	2.4
medium	0.2
morph	0.24
open	0.18
press	0.12
quick	0.15
search	0.26
settle	0.32
short	0.16

---

EASE

const EASE: object

Shared easing roles. Keep the overdamped spring for interruptible movement; the bounce and reveal curves preserve the existing CSS roles that do not have spring semantics.

Type Declaration

Name	Type
bounce	[number, number, number, number]
drawer	[number, number, number, number]
feedback	[number, number, number, number]
inOut	[number, number, number, number]
out	[number, number, number, number]
reveal	[number, number, number, number]
spring	[number, number, number, number]

---

EASE_CSS

const EASE_CSS: object

CSS forms of EASE, including the native curves used by existing controls.

Type Declaration

Name	Type
bounce	string
drawer	string
feedback	string
inOut	string
linear	"linear"
out	string
reveal	string
spring	string
standard	"ease"
standardIn	"ease-in"
standardInOut	"ease-in-out"
standardOut	"ease-out"

---

EDGE_SWIPE_ZONE_PX

const EDGE_SWIPE_ZONE_PX: 20 = 20

The iOS back-swipe zone: a touch that starts this close to the left edge may open the sidebar sheet; anywhere else it may not (the Calendar’s horizontal day scroll keeps every other horizontal swipe).

---

Fab

const Fab: Component

---

FieldPopover

const FieldPopover: Component

---

FileCollection

const FileCollection: Component

---

FileIcon

FileIcon: any

---

FileName

const FileName: Component

---

FileThumb

const FileThumb: Component

---

FIRST_DAY_CHOICES

const FIRST_DAY_CHOICES: readonly ["system", "sunday", "monday", "saturday"]

---

FloatingSidebar

const FloatingSidebar: Component

---

FloatingSurface

const FloatingSurface: Component

---

HighlightOverlay

const HighlightOverlay: Component

---

IconLabel

const IconLabel: Component

---

inlineAudioPlayback

const inlineAudioPlayback: InlineAudioPlaybackState

Shared playback state for Calendar, Search, and voice memo controls. Playback helpers own its updates (#622, #822; DESIGN §38).

---

InlineRename

const InlineRename: Component

Let a User edit a name in place. Bind value and set textAlignment to match the static name. The caller must save or cancel the edit. Issue #1017; DESIGN §34.

---

Inspector

const Inspector: Component

---

InspectorRow

const InspectorRow: Component

Add one label and value to InspectorSection. The label appears as dt; put the value in the child snippet. Issue #659; DESIGN §34.

---

InspectorSection

const InspectorSection: Component

Group Inspector content under a named heading. By default, children go inside a description list. Set rows to false for content such as loading or error text. busy sets aria-busy. Issue #659; DESIGN §34.

---

ItemCard

const ItemCard: Component

Show a non-interactive summary for an item. Set kind and title; optional text and media come from props. The host owns selection and actions. size controls the layout. Issue #822; DESIGN §§38–39.

---

ItemPreview

const ItemPreview: Component

---

Kbd

const Kbd: Component

---

KEY_ZOOM_STEP

const KEY_ZOOM_STEP: 1.25 = 1.25

The keyboard step (Cmd/Ctrl + and −).

---

LinkedHeading

const LinkedHeading: Component

---

LOD_HYSTERESIS

const LOD_HYSTERESIS: 3 = 3

A zoom must pass a threshold by this much to switch, so resting on it never flickers.

---

LOD2_HOUR

const LOD2_HOUR: 44 = 44

Level-of-detail tiers (§39): 1 titles, 2 time and tags (from 44 px an hour), 3 attachment decks (from 84).

---

LOD3_HOUR

const LOD3_HOUR: 84 = 84

---

LogEntryEditor

const LogEntryEditor: Component

---

MAX_HOUR_HEIGHT

const MAX_HOUR_HEIGHT: 160 = 160

---

Menu

Menu: Component<Props, { }, "surfaceEl">

---

MIN_HOUR_HEIGHT

const MIN_HOUR_HEIGHT: 24 = 24

The smallest, default and largest hour height in CSS pixels.

---

MiniMonth

const MiniMonth: Component

---

ModeHeader

const ModeHeader: Component

---

ModeIcon

const ModeIcon: Component

Show the decorative glyph for a Tab. Set modeId to the Tab ID. The Calendar glyph also shows the current day and updates when that day changes. Issues #1095–#1097; DESIGN §34.

---

MonthGrid

const MonthGrid: Component

---

NOTE_LINK_INTENT_REST_MS

const NOTE_LINK_INTENT_REST_MS: 180 = 180

Shared intent timing for delayed prefetch in pointer and keyboard UI paths. A 180 ms rest cancels quick flyovers while giving a deliberate Note link time to warm its route and body (#608, #639).

---

NoteMentionsCard

const NoteMentionsCard: Component

---

NoteProperties

const NoteProperties: Component

---

OPENING_MOTION

const OPENING_MOTION: object

Shared opening choreography for the bottom capsule, menus and popovers. The last staggered item settles at exactly 500 ms: 90 ms + (4 × 25 ms) + 310 ms. Keep the CSS morph on this same contract.

The 1.08 damping ratio is overdamped, so items rise to rest without a bounce. The width/height curve is the shared cubic approximation of easeOutQuint.

Type Declaration

Name	Type
cap	500
countRoll	180
dampingRatio	1.08
easeOutQuint	string
exitFade	120
firstItemDelay	90
itemOffset	12
itemRise	310
itemStagger	25
maxStaggerIndex	4
morph	200

---

OverlaySurface

const OverlaySurface: Component

---

Pill

const Pill: Component

---

PillGroup

const PillGroup: Component

---

POINT_ENTRY_MINUTES

const POINT_ENTRY_MINUTES: 20 = 20

A log entry without an end is a point in time; give it a visual length.

---

PopoverSurface

const PopoverSurface: Component

---

PrimaryPill

const PrimaryPill: Component

---

ProgressiveBlur

const ProgressiveBlur: Component

---

QuickLook

const QuickLook: Component

---

RECENTRE_MARGIN

const RECENTRE_MARGIN: 150 = 150

A settled scroll closer than this many days to an edge re-centres.

---

RepairList

const RepairList: Component

---

REQUEST_NEXT_STEP

const REQUEST_NEXT_STEP: "Check your connection, then try again." = "Check your connection, then try again."

The plain next step for a titled failure whose cause the client cannot name (#869). The heading already says what failed, so the message under it says what to do. Callers pass it in place of a sentence that repeats the title.

---

RequestState

const RequestState: Component

Show the loading or error state for a request. Retry appears only when both its label and callback are set. Use variant="card" for the shared page Card treatment. Issue #869; DESIGN §34.

---

SegmentedControl

const SegmentedControl: Component

---

Select

const Select: Component

---

SelectionBar

const SelectionBar: Component<Props, { }, "">

---

SettingRow

const SettingRow: Component

---

SidebarSectionHeader

const SidebarSectionHeader: Component

---

StatusPill

const StatusPill: Component

---

TabBar

const TabBar: Component

---

TagPill

const TagPill: Component

---

TextInput

const TextInput: Component

Show a text field with shared colours and focus styling. Bind value; other native input attributes pass through to the field. Issue #407; DESIGN §3.

---

TextView

const TextView: Component

---

THEME_FAMILIES

const THEME_FAMILIES: ThemeFamilyDef[]

---

THEME_FAMILY_IDS

const THEME_FAMILY_IDS: ThemeFamilyId[]

---

THEME_GROUPS

const THEME_GROUPS: object[]

Themes grouped by palette scheme for callers that still need the registry view.

Type Declaration

Name	Type
group	ThemeGroup
themes	ThemeDef[]

---

THEME_IDS

const THEME_IDS: ThemeId[]

---

ThemePicker

const ThemePicker: Component

---

THEMES

const THEMES: ThemeDef[]

---

TIME_FORMATS

const TIME_FORMATS: readonly ["system", "24_hour", "12_hour"]

---

TIME_ZONE_CHIP_CLASS

const TIME_ZONE_CHIP_CLASS: "cal-time-zone-chip" = "cal-time-zone-chip"

Shared inline time-zone label contract for Calendar and Daily Log text.

---

TimeGrid

const TimeGrid: Component

---

TIMEZONE_CITIES

const TIMEZONE_CITIES: Readonly<Record<string, TimezoneCity>>

---

TimeZoneChip

const TimeZoneChip: Component

Show a time zone beside a Calendar time. The chip stays hidden when the zone matches userZone. If userZone is omitted, the User’s system time zone is used for comparison. DESIGN §29 C12 and §34 (Calendar preview).

---

TodayButton

const TodayButton: Component

---

Toggle

const Toggle: Component

---

TOOLTIP_GAP

const TOOLTIP_GAP: 8 = 8

Space between the trigger and the bubble (px).

---

TOOLTIP_MARGIN

const TOOLTIP_MARGIN: 8 = 8

Minimum space between the bubble and a viewport edge (px).

---

TooltipLayer

const TooltipLayer: Component<Record<string, never>, { }, "">

---

TRACK_DAYS

const TRACK_DAYS: 2001 = 2001

---

UIHeading

const UIHeading: Component

---

VoicePill

const VoicePill: Component

Show idle, requesting, recording, or error controls for a voice memo. The caller manages capture, saving, discard confirmation, and Undo. Issue #617; DESIGN §38.

---

VoicePlayback

const VoicePlayback: Component

Play a voice memo with seek and speed controls. Use the same stable key as compact controls so all surfaces share one playback state. If omitted, src is the key. Issues #617, #622, #822; DESIGN §38.

---

VoicePlayToggle

const VoicePlayToggle: Component

Show the shared play or pause button for a voice memo row. The host handles onplay because it can resolve the audio source. Use the same key as VoicePlayback. The button stops clicks from reaching its row. Issue #822; DESIGN §38.

---

VoiceRecordingPill

const VoiceRecordingPill: Component

Show recording controls for Composer or Calendar. The caller manages microphone access and saving. This component manages focus and asks for confirmation before Escape discards an active recording. Issue #619; DESIGN §34.

---

WARM_WINDOW_MS

const WARM_WINDOW_MS: 400 = 400

How long the group stays warm after a tooltip closes.

---

WEEK_LANE_MINIMUM_WIDTH

const WEEK_LANE_MINIMUM_WIDTH: 64 = 64

A Week card needs one short title word plus its horizontal padding (#969).

---

YearHeatmap

const YearHeatmap: Component

Functions

absoluteLink()

absoluteLink(path): string

Absolute URL for an in-app deep link path (DESIGN §33).

Parameters

Parameter	Type
path	string

Returns

string

---

activityCount()

activityCount(day): number

Activity count used by the Year heat map and Month density.

Parameters

Parameter	Type
day	CalendarDay | undefined

Returns

number

---

activityDeckLaneWidth()

activityDeckLaneWidth(columnWidth, columns, maxLanes, scale): number

Calculate the horizontal space available to one packed Activity lane (#589).

Parameters

Parameter	Type
columnWidth	number
columns	number
maxLanes	number
scale	number

Returns

number

---

activityDeckPresentation()

activityDeckPresentation(laneWidth, verticalSpan, scale, added): object

Keep a deck inside its lane and free time, reserving room for the Added count when it fits (#589, #624).

Parameters

Parameter	Type
laneWidth	number
verticalSpan	number
scale	number
added	boolean

Returns

object

Name	Type
compact	boolean
size	number

---

activityPlanDurationMinutes()

activityPlanDurationMinutes(hourHeight): number

Return the time interval that can display one Activity thumbnail at this zoom (#589).

Parameters

Parameter	Type
hourHeight	number

Returns

number

---

activityStacks()

activityStacks(day, visible): ActivityStack[]

Busy days (DESIGN §30 C8): one stack per kind, hour and Photo date role. Added Photos use the same Calendar items as Week and Day, so the upload-day deck can show the shared carousel while legacy range rows stay a fallback. Stacks sort by hour and kind so the row reads in time order.

Parameters

Parameter	Type
day	CalendarDay | undefined
visible	ReadonlySet<ActivityKind>

Returns

ActivityStack[]

---

addDays()

addDays(date, delta): string

Add N days to a YYYY-MM-DD date string, returning a new YYYY-MM-DD.

Parameters

Parameter	Type
date	string
delta	number

Returns

string

---

addMonths()

addMonths(date, delta): string

Parameters

Parameter	Type
date	string
delta	number

Returns

string

---

addYears()

addYears(date, delta): string

Parameters

Parameter	Type
date	string
delta	number

Returns

string

---

anchoredScrollTop()

anchoredScrollTop(options): number

The scroll position that keeps the time under anchorY in place when the hour height changes from from to to. anchorY is the pointer’s offset from the scroller’s top edge; contentTop is the offset of 00:00 from the top of the scrolled content (the sticky header plus padding).

Parameters

Parameter	Type
options	{ anchorY: number; contentTop: number; from: number; scrollTop: number; to: number; }
options.anchorY	number
options.contentTop	number
options.from	number
options.scrollTop	number
options.to	number

Returns

number

---

anchorToRect()

anchorToRect(rect, align?, gap?): RectAnchor

Anchor a floating surface to its trigger’s rect: open gap px below it, flip to gap px above it when there is no room below, and align the surface’s left edge ('left') or right edge ('right') with the trigger’s. The scale-in origin is the trigger’s centre, so the surface grows out of the control that opened it (Apple/Emil origin-aware popovers).

Pure (takes a rect, not an element) so it is unit-testable without layout; FloatingSurface reads the rect at placement time and on resize.

Parameters

Parameter	Type
rect	{ bottom: number; left: number; right: number; top: number; }
rect.bottom	number
rect.left?	number
rect.right?	number
rect.top?	number
align?	HAlign
gap?	number

Returns

RectAnchor

---

attachmentCountLabel()

attachmentCountLabel(count): string

Parameters

Parameter	Type
count	number

Returns

string

---

attachmentFamily()

attachmentFamily(target, mediaType?, displayName?): AttachmentFamily

Resolve attachment family from API metadata, file extension, or recorder label (#628).

Parameters

Parameter	Type
target	string
mediaType?	string | null
displayName?	string | null

Returns

AttachmentFamily

---

attachmentFileName()

attachmentFileName(target): string

The indexed file name behind an optional attachment label.

Parameters

Parameter	Type
target	string

Returns

string

---

attachmentKindLabel()

attachmentKindLabel(attachment): string

Return the short kind label shown in Calendar preview rows (#628). The full indexed name remains in the shared tooltip so a narrow row stays scannable.

Parameters

Parameter	Type
attachment	CalendarAttachment

Returns

string

---

attachmentRefs()

attachmentRefs(attachments): AttachmentRef[]

Build bounded view data from real API attachments without resolving paths on the client.

Parameters

Parameter	Type
attachments	readonly CalendarAttachment[]

Returns

AttachmentRef[]

---

attachmentShareHref()

attachmentShareHref(attachment): string | null

Build a shareable link only from stable API identities or a web URL (#628).

Parameters

Parameter	Type
attachment	CalendarAttachment

Returns

string | null

---

attachmentThumbUrl()

attachmentThumbUrl(hash, size?): string

Build a thumbnail URL from its content hash; callers never pass a path.

Parameters

Parameter	Type
hash	string
size?	number

Returns

string

---

audioDisplayName()

audioDisplayName(fileName, displayName?): string

Give an audio attachment one display name in the Agenda, preview and Quick Look. Keep the indexed name for tooltips and downloads; only the visible title drops its extension. Recorder names become stable clock labels even when Files adds a unique prefix before the preserved recorder display title.

Parameters

Parameter	Type
fileName	string
displayName?	string | null

Returns

string

---

buildRange()

buildRange(opts?): string[]

Build the strip’s date range as an ascending list of YYYY-MM-DD strings.

We anchor on today and extend pastDays into the past and futureDays into the future, then widen to whole locale weeks on both ends so the week-boundary markers and the week blob read cleanly. The feed’s loaded days are unioned in via coverDates, so scrolling back through history that predates the default window still lights up matching cells.

Defaults: ~2 weeks back + the current week forward — a sensible, extensible window (DESIGN: “recent ~2 weeks, extensible”).

Parameters

Parameter	Type	Description
opts?	{ coverDates?: string[]; firstDay?: WeekDay; futureDays?: number; pastDays?: number; today?: string; }	-
opts.coverDates?	string[]	-
opts.firstDay?	WeekDay	First day of the week; defaults to the user’s locale.
opts.futureDays?	number	-
opts.pastDays?	number	-
opts.today?	string	-

Returns

string[]

---

calendarDateInTimeZone()

calendarDateInTimeZone(instant, timeZone): string

Stable ISO calendar date for comparing instants inside one named zone.

Parameters

Parameter	Type
instant	string | number | Date
timeZone	string

Returns

string

---

calendarHref()

calendarHref(view, date): string

Parameters

Parameter	Type
view	CalendarView
date	string

Returns

string

---

calendarItemActions()

calendarItemActions(item, available): CalendarItemAction[]

Build the one ordered action list used by Calendar’s hover card and item context menu. Callers only supply availability; labels, order and groups stay shared as DESIGN §34 and issue #581 require.

Parameters

Parameter	Type
item	CalendarActionItem
available	CalendarItemActionAvailability

Returns

CalendarItemAction[]

---

calendarLogPartForDay()

calendarLogPartForDay(sourceDate, log, date): CalendarLogPart | null

Return the Log part that belongs in date, while keeping the original Log and its Daily note date intact for links, previews and edits (#469).

Parameters

Parameter	Type
sourceDate	string
log	CalendarLog
date	string

Returns

CalendarLogPart | null

---

calendarSnapEdges()

calendarSnapEdges(day): CalendarSnapItemEdge[]

Return the stable, visible edges that a drag in one day column can meet. The caller memoizes this by CalendarDay so pointer movement only scans the short edge list; continued Logs keep their source-day identity (#536).

Parameters

Parameter	Type
day	CalendarDay

Returns

CalendarSnapItemEdge[]

---

calendarTaskPartForDay()

calendarTaskPartForDay(task, date): CalendarTask | null

Add the timed part of a Task to one date. A timed start-to-due pair is a half-open range; one timed property is a point on its property date. When a Task has no explicit placement, its creation minute is a timed point. Old date-only Tasks remain in the all-day lane (#469, #655; DESIGN §30 C12).

Parameters

Parameter	Type
task	CalendarTask
date	string

Returns

CalendarTask | null

---

calendarTimePartForDay()

calendarTimePartForDay(startDate, start, endDate, end, date): CalendarTimePart | null

Return one visible local-day part of a timed range (#469).

Parameters

Parameter	Type
startDate	string
start	string
endDate	string
end	string
date	string

Returns

CalendarTimePart | null

---

calendarTimeZone()

calendarTimeZone(): string

The selected User zone, or this Installation’s system zone before a switch.

Returns

string

---

calendarWindowRange()

calendarWindowRange(window): { from: string; to: string; } | null

Return the inclusive range a MiniMonth should mark, or null for no band.

Parameters

Parameter	Type
window	CalendarWindow | null

Returns

{ from: string; to: string; } | null

---

canonicalTimeZone()

canonicalTimeZone(timeZone): string

Canonical IANA identifier reported by Intl for a supported time zone.

Parameters

Parameter	Type
timeZone	string

Returns

string

---

capsuleCountTransition()

capsuleCountTransition(_node, params?, options?): { css: (t) => string; duration: number; easing?: undefined; } | { css: (t) => string; duration: 180; easing: (t) => number; }

Roll a changed selection count upward while the replacement enters below.

Parameters

Parameter	Type
_node	Element
params?	{ enabled?: boolean; reducedMotion?: boolean; }
params.enabled?	boolean
params.reducedMotion?	boolean
options?	{ direction?: "in" | "out" | "both"; }
options.direction?	"in" | "out" | "both"

Returns

Type Literal

{ css: (t) => string; duration: number; easing?: undefined; }

---

Type Literal

{ css: (t) => string; duration: 180; easing: (t) => number; }

Name	Type
css()	(t) => string
duration	180
easing()	(t) => number

---

capsulePaneTransition()

capsulePaneTransition(_node, params?, _options?): { css: (t) => string; duration: number; easing?: undefined; } | { css: (t) => string; duration: 200; easing: (t) => number; }

Cross-fade panes; keep a returning capsule surface through its measured morph.

Parameters

Parameter	Type
_node	Element
params?	{ enabled?: boolean; morphOut?: boolean; reducedMotion?: boolean; }
params.enabled?	boolean
params.morphOut?	boolean
params.reducedMotion?	boolean
_options?	{ direction?: "in" | "out" | "both"; }
_options.direction?	"in" | "out" | "both"

Returns

Type Literal

{ css: (t) => string; duration: number; easing?: undefined; }

---

Type Literal

{ css: (t) => string; duration: 200; easing: (t) => number; }

Name	Type
css()	(t) => string
duration	200
easing()	(t) => number

---

cascadeItemDelay()

cascadeItemDelay(index): number

One capped delay keeps long, scrolling toolbars and surface lists inside the 500 ms cap.

Parameters

Parameter	Type
index	number

Returns

number

---

cascadeItemTransition()

cascadeItemTransition(_node, params?, options?): { css: (t) => string; delay: number; duration: number; easing?: undefined; } | { css: (t) => string; delay?: undefined; duration: 120; easing?: undefined; } | { css: (t) => string; delay: number; duration: 310; easing: (t) => number; }

Svelte transition used by opening surfaces and capsule action rows.

Parameters

Parameter	Type
_node	Element
params?	{ enabled?: boolean; index?: number; reducedMotion?: boolean; visibleOnly?: boolean; }
params.enabled?	boolean
params.index?	number
params.reducedMotion?	boolean
params.visibleOnly?	boolean
options?	{ direction?: "in" | "out" | "both"; }
options.direction?	"in" | "out" | "both"

Returns

Type Literal

{ css: (t) => string; delay: number; duration: number; easing?: undefined; }

---

Type Literal

{ css: (t) => string; delay?: undefined; duration: 120; easing?: undefined; }

---

Type Literal

{ css: (t) => string; delay: number; duration: 310; easing: (t) => number; }

Name	Type
css()	(t) => string
delay	number
duration	310
easing()	(t) => number

---

cascadeOverdamped()

cascadeOverdamped(t): number

Normalised step response for an overdamped spring. Eight natural time units fit the requested stiffness into the 310 ms rise while retaining ζ = 1.08.

Parameters

Parameter	Type
t	number

Returns

number

---

claimAudioFocus()

claimAudioFocus(owner): void

Give audio focus to media outside the shared player. The shared player and the previous foreign element pause, so only one sound plays in the app.

Parameters

Parameter	Type
owner	{ pause: void; }
owner.pause

Returns

void

---

clampHour()

clampHour(height): number

Parameters

Parameter	Type
height	number

Returns

number

---

clearInlineAudioPlayback()

clearInlineAudioPlayback(): void

Release the single player when its owning page leaves the view.

Returns

void

---

configureDateTimePreferences()

configureDateTimePreferences(value): DateTimePreferences

Apply the User’s saved date, time and week-start choices to every UI surface.

Parameters

Parameter	Type
value	unknown

Returns

DateTimePreferences

---

copyLink()

copyLink(href): Promise<boolean>

Copy a deep link (DESIGN §33): an in-app path or an absolute URL, resolved against the current origin at call time. Every Copy link surface (the CopyLink control, context menus, sheets) copies through this one function.

Parameters

Parameter	Type
href	string

Returns

Promise<boolean>

---

copyText()

copyText(text): Promise<boolean>

Copy plain text. Resolves true on success and false on any failure.

Parameters

Parameter	Type
text	string

Returns

Promise<boolean>

---

createCalendarWindow()

createCalendarWindow(anchor, span): CalendarWindow

Create the initial snapshot that the active page wraps in Svelte state.

Parameters

Parameter	Type
anchor	string
span	number

Returns

CalendarWindow

---

createInteractiveSpring()

createInteractiveSpring(initial, onUpdate, options?): InteractiveSpring

A single-value, retargetable overdamped spring for finger-driven surfaces. Its natural frequency comes from the capsule’s eight-time-unit response and 310 ms rise. A retarget samples the live position and velocity before it builds the next curve, so interrupted gestures do not jump or restart cold. Keyboard retargets use the same spring as pointer retargets (#611). The shared 500 ms cap also bounds a release with unusually high momentum.

Parameters

Parameter	Type
initial	number
onUpdate	(value) => void
options?	InteractiveSpringOptions

Returns

InteractiveSpring

---

createLatestPointerFrameQueue()

createLatestPointerFrameQueue(requestFrame?, cancelFrame?): object

Coalesce a single pointer’s preview work to its latest sample per animation frame. Pointer-up flushes that sample so a drop keeps the final position (#751).

Parameters

Parameter	Type
requestFrame?	(callback) => number
cancelFrame?	(handle) => void

Returns

object

Name	Type
cancel()	(pointer?) => void
enqueue()	(pointer, update) => void
flush()	(pointer) => void

---

crossesMidnight()

crossesMidnight(entry): boolean

True for a range that ends on the next day (23:00 - 01:00, #99).

Parameters

Parameter	Type
entry	{ end: string | null; start: string; }
entry.end	string | null
entry.start	string

Returns

boolean

---

currentDateTimePreferences()

currentDateTimePreferences(): DateTimePreferences

Current formatter preferences, including their reactive Svelte state.

Returns

DateTimePreferences

---

dateFormat()

dateFormat(locale, options): DateTimeFormat

A shared, memoised new Intl.DateTimeFormat(locale, options). Use it for every app-owned date label, including fixed-locale chart labels; the cache keeps repeated render and tooltip work off the formatter constructor.

Parameters

Parameter	Type
locale	LocalesArgument
options	DateTimeFormatOptions

Returns

DateTimeFormat

---

dayDiff()

dayDiff(from, to): number

Whole days from from to to (DST-safe: counts calendar days).

Parameters

Parameter	Type
from	string
to	string

Returns

number

---

draggablePopover()

draggablePopover(node, initial): object

Parameters

Parameter	Type
node	HTMLElement
initial	DraggablePopoverOptions

Returns

object

Name	Type
destroy()	() => void
update()	(next) => void

---

durationMs()

durationMs(seconds): number

Convert shared seconds for Svelte and honor reduced motion.

Parameters

Parameter	Type
seconds	number

Returns

number

---

emptyDay()

emptyDay(date): CalendarDay

Parameters

Parameter	Type
date	string

Returns

CalendarDay

---

entryRange()

entryRange(entry): object

Parameters

Parameter	Type
entry	{ end: string | null; start: string; }
entry.end	string | null
entry.start	string

Returns

object

Name	Type
end	number
point	boolean
start	number

---

eventDotBackground()

eventDotBackground(tags, overrides?): string

The CSS background of an event’s colour dot (EntryCard row marker, Composer event chip). Area tags are an event’s primary categories: several blend into one radial swatch. Without area tags the first visible tag is the fallback (older/imported entries); an untagged event uses the theme accent. Reserved _calternal/* tags never colour a dot. One helper so the chip that names an event always matches the dot on its card.

Parameters

Parameter	Type
tags	readonly string[]
overrides?	Record<string, string>

Returns

string

---

eventHref()

eventHref(id, date?, sourceId?): string

Build an Event deep link; URL layers use their stable source ID and day.

Parameters

Parameter	Type
id	string
date?	string
sourceId?	string | null

Returns

string

---

eventTint()

eventTint(tags, layerColor?): EventTint

Resolve a tag tint or validated external layer colour for every Calendar surface.

Parameters

Parameter	Type
tags	readonly string[]
layerColor?	string | null

Returns

EventTint

---

familyForTheme()

familyForTheme(id): ThemeFamilyId

Return the family that owns a saved palette id.

Parameters

Parameter	Type
id	ThemeId

Returns

ThemeFamilyId

---

familyVariants()

familyVariants(family, preference): readonly ThemeId[]

Return the variant choices allowed by a saved colour scheme choice (#506, DESIGN §35).

Parameters

Parameter	Type
family	ThemeFamilyId
preference	ThemeSchemePreference

Returns

readonly ThemeId[]

---

fileGlyphKind()

fileGlyphKind(name, mime?, path?): FileGlyphKind

Pick a preview kind from Files’ indexed MIME; path is only for voice-memo identity (#620/#851).

Parameters

Parameter	Type
name	string
mime?	string | null
path?	string | null

Returns

FileGlyphKind

---

fileHref()

fileHref(id): string

Parameters

Parameter	Type
id	string

Returns

string

---

filesThumbnailUrl()

filesThumbnailUrl(hash, size?, kind?): string

Build the shared Files thumbnail route with its renderer-specific cache key.

Parameters

Parameter	Type
hash	string
size?	256 | 1024
kind?	ThumbnailKind

Returns

string

---

findCalendarColumnDateAt()

findCalendarColumnDateAt(columns, clientX): string | null

Find a rendered date column at a viewport x coordinate without scanning all columns (#751).

Parameters

Parameter	Type
columns	readonly CalendarColumnBounds[]
clientX	number

Returns

string | null

---

firstVisibleIndex()

firstVisibleIndex(scrollLeft, columnWidth): number

The first column whose left edge is at or before scrollLeft (snapped within half a pixel).

Parameters

Parameter	Type
scrollLeft	number
columnWidth	number

Returns

number

---

fixedContainingBlockOrigin()

fixedContainingBlockOrigin(parent): object

The viewport position of the containing block that a position: fixed child of parent would be placed against: { x: 0, y: 0 } for the viewport itself, or the origin of the nearest containing-block ancestor’s padding box, minus its scroll offset (a fixed child scrolls with that ancestor’s content). Subtract this from viewport coordinates before writing top/left. Transforms that scale or rotate are not compensated; menus never sit inside those.

Parameters

Parameter	Type
parent	Element | null

Returns

object

Name	Type
x	number
y	number

---

formatClockRange()

formatClockRange(start, end?, locale?): string

Format one local clock value or a range with the shared spaced en dash (§38, #413).

Parameters

Parameter	Type
start	string | null | undefined
end?	string | null
locale?	LocalesArgument

Returns

string

---

formatClockTime()

formatClockTime(clock, locale?): string

Format a local-naive clock with the selected cycle. UTC is a formatting anchor, not the User’s zone: these labels must not convert wall times (#549).

Parameters

Parameter	Type
clock	string
locale?	LocalesArgument

Returns

string

---

formatCompactClockTime()

formatCompactClockTime(clock, locale?): string

A compact clock label for the Calendar’s now pill, without its day period.

Parameters

Parameter	Type
clock	string
locale?	LocalesArgument

Returns

string

---

formatDateInTimeZone()

formatDateInTimeZone(instant, timeZone, locale?): string

Format the calendar date for an absolute instant in an explicit time zone. Auto uses this for its next-boundary label so date patterns remain owned by the shared formatter instead of each feature constructing Intl formatters.

Parameters

Parameter	Type
instant	string | number | Date
timeZone	string
locale?	LocalesArgument

Returns

string

---

formatDateParts()

formatDateParts(date): object

Parameters

Parameter	Type
date	string

Returns

object

Name	Type
day	string
relative	string
sub	string

---

formatDateRange()

formatDateRange(startValue, endValue, locale?): string

Format a date range with the selected short-date pattern or system locale. Without a confirmed User time zone, the date values already use this Installation’s local zone; compare their years directly. Resolving the system zone for every visible range cell rebuilt Intl formatters on each picker page turn (#391, DESIGN §47). With an override, compare dates in that zone so ranges that cross its year boundary keep the year in the label.

Parameters

Parameter	Type
startValue	DateInput
endValue	DateInput
locale?	LocalesArgument

Returns

string

---

formatDateTime()

formatDateTime(value, locale?, timeZone?): string

A short date and selected time, used for edited/modified timestamps.

Parameters

Parameter	Type
value	DateInput
locale?	LocalesArgument
timeZone?	string

Returns

string

---

formatDateTitleParts()

formatDateTitleParts(value, locale?): object

Calendar header pieces keep the emphasis on the date’s primary unit.

Parameters

Parameter	Type
value	DateInput
locale?	LocalesArgument

Returns

object

Name	Type
rest	string
short	string
strong	string
sub	string

---

formatDuration()

formatDuration(milliseconds): string

Clock form for a media duration in milliseconds: “0:42” or “1:02:05”.

Parameters

Parameter	Type
milliseconds	number

Returns

string

---

formatHour()

formatHour(value, locale?, timeZone?): string

Format an hour label with the selected cycle and no minute field.

Parameters

Parameter	Type
value	DateInput
locale?	LocalesArgument
timeZone?	string

Returns

string

---

formatHours()

formatHours(minutes, locale?, fractionDigits?): string

Format a minute total as locale-aware hours. By default up to 2 decimals with no trailing zeroes (“5.25”, “5”). With fractionDigits, exactly that many decimals (“3.7”, “1.0”), for a caller that needs a fixed-width shape (the analytics delta chip). The decimal separator follows the locale (“3,7” in de).

Parameters

Parameter	Type
minutes	number
locale?	LocalesArgument
fractionDigits?	number

Returns

string

---

formatInstantDateTime()

formatInstantDateTime(instant, timeZone, locale?): string

Format an absolute instant with the selected date and time preferences.

Parameters

Parameter	Type
instant	string | Date
timeZone	string
locale?	LocalesArgument

Returns

string

---

formatInstantTime()

formatInstantTime(instant, timeZone, locale?): string

Format an absolute instant in the selected time cycle and requested zone.

Parameters

Parameter	Type
instant	string | Date
timeZone	string
locale?	LocalesArgument

Returns

string

---

formatItemDate()

formatItemDate(value, locale?): string

The compact date for item details (Inspector rows, Task dates, links to a day): short weekday and month, and the year only outside the current year. One format keeps “Linked from”, “Created” and “Where” consistent (#659).

Parameters

Parameter	Type
value	DateInput
locale?	LocalesArgument

Returns

string

---

formatItemDateTime()

formatItemDateTime(value, clock?, locale?): string

formatItemDate plus an optional local-naive clock, joined by DATE_TIME_SEPARATOR.

Parameters

Parameter	Type
value	DateInput
clock?	string | null
locale?	LocalesArgument

Returns

string

---

formatLocalClock()

formatLocalClock(clock, locale?): string

Format a local wall-clock value without changing its time zone.

Parameters

Parameter	Type
clock	string
locale?	LocalesArgument

Returns

string

---

formatLocaleDate()

formatLocaleDate(date, locale?): string

Format a YYYY-MM-DD as a numeric calendar date in the requested locale.

Day-file dates are local-naive values. Constructing the Date with numeric local parts keeps a date near midnight in a negative offset zone from crossing into the previous day, unlike new Date('YYYY-MM-DD'), which is specified as UTC. Passing no locale lets the browser choose its preferred numeric order and separators; the optional locale is useful for tests and deterministic previews.

Parameters

Parameter	Type
date	string
locale?	LocalesArgument

Returns

string

---

formatLocalTime()

formatLocalTime(date, clock, locale?): string

Format a local-naive clock value on its Daily note date.

The journal API returns start as HH:MM, not as a timestamp. Combining those local-naive fields avoids parsing the clock as an invalid Date and keeps the displayed time tied to the date selected in the DateStrip.

Parameters

Parameter	Type
date	string
clock	string
locale?	LocalesArgument

Returns

string

---

formatLongDate()

formatLongDate(value, options?, locale?): string

Format a date with localized month and weekday names in the selected or explicit locale order.

Parameters

Parameter	Type
value	DateInput
options?	LongDateOptions
locale?	LocalesArgument

Returns

string

---

formatMonth()

formatMonth(value, width?, locale?, timeZone?): string

Parameters

Parameter	Type
value	DateInput
width?	"long" | "short" | "narrow"
locale?	LocalesArgument
timeZone?	string

Returns

string

---

formatMonthYear()

formatMonthYear(value, width?, locale?, timeZone?): string

Parameters

Parameter	Type
value	DateInput
width?	"long" | "short"
locale?	LocalesArgument
timeZone?	string

Returns

string

---

formatNavDate()

formatNavDate(date, locale?): string

Compact day label for navigation crumbs: “17 Sep” (day, short month in the user’s locale); null is today.

Parameters

Parameter	Type
date	string | null
locale?	LocalesArgument

Returns

string

---

formatNumber()

formatNumber(value, locale?, options?): string

Locale-aware number grouping for counts and sizes across UI surfaces. A decimal string ("-1234.56") is formatted exactly, without a detour through floating point: Money amounts use this (DESIGN §48).

Parameters

Parameter	Type
value	number | `${number}`
locale?	LocalesArgument
options?	NumberFormatOptions

Returns

string

---

formatRelativeDate()

formatRelativeDate(value, now?, locale?): string

Day label for relative surfaces. Older dates follow the chosen short format.

Parameters

Parameter	Type
value	DateInput
now?	Date
locale?	LocalesArgument

Returns

string

---

formatShortDate()

formatShortDate(value, locale?, preference?): string

Format a date with the User’s selected short-date pattern or system locale.

Parameters

Parameter	Type
value	DateInput
locale?	LocalesArgument
preference?	"system" | "dmy_slash_padded_short" | "mdy_slash_short" | "dmy_slash_short" | "mdy_slash_long" | "dmy_slash_padded_long" | "dmy_dot" | "dmy_dash" | "ymd_slash" | "ymd_dot" | "iso"

Returns

string

---

formatStamp()

formatStamp(d?): string

Local-naive YYYY-MM-DD HH:MM:SS stamp for a new day file’s frontmatter. Ported from the CLI’s vault formatStamp so a web-minted day file’s frontmatter matches the CLI byte-for-byte (common daily-note convention; no timezone).

Parameters

Parameter	Type
d?	Date

Returns

string

---

formatTime()

formatTime(value, locale?, timeZone?, seconds?): string

Format a time using the selected cycle; include seconds for detailed media metadata.

Parameters

Parameter	Type
value	DateInput
locale?	LocalesArgument
timeZone?	string
seconds?	boolean

Returns

string

---

formatTimeGridRangeLabels()

formatTimeGridRangeLabels(start, end, endClock?, locale?): object

The same formatted clock values used by the live drag labels and drop announcement.

Parameters

Parameter	Type
start	number
end	number
endClock?	string
locale?	LocalesArgument

Returns

object

Name	Type
announcement	string
combined	string
end	string
start	string

---

formatTimeZoneLabel()

formatTimeZoneLabel(timezone): string

Match Calendar’s readable spelling without changing the stored zone ID.

Parameters

Parameter	Type
timezone	string

Returns

string

---

formatWeekday()

formatWeekday(value, width?, locale?, timeZone?): string

Localized weekday names in the device zone or an explicit time zone.

Parameters

Parameter	Type
value	DateInput
width?	"long" | "short" | "narrow"
locale?	LocalesArgument
timeZone?	string

Returns

string

---

formatYear()

formatYear(value, locale?): string

Format a year using the Installation’s locale.

Parameters

Parameter	Type
value	DateInput
locale?	LocalesArgument

Returns

string

---

fromMinutes()

fromMinutes(minutes): string

Parameters

Parameter	Type
minutes	number

Returns

string

---

gridItemAttachment()

gridItemAttachment(item): CalendarAttachment

Adapt the range API’s standalone item to the shared deck without rebuilding a path (#822, §39).

Parameters

Parameter	Type
item	GridItem

Returns

CalendarAttachment

---

gridItemHref()

gridItemHref(entry): string | null

A standalone Calendar item’s own stable link (DESIGN §33): Notes /n/, Photos /p/, other files /f/. Null when the item has no stable ID yet. Calendar previews and the Activity context menu share it (#822).

Parameters

Parameter	Type
entry	Pick<GridItem, "kind" | "itemId" | "noteId">

Returns

string | null

---

heatLevels()

heatLevels(counts): (count) => 0 | 1 | 2 | 3 | 4

Heat level 0–4 for the Year map. Quantiles keep one busy day from flattening the rest.

Parameters

Parameter	Type
counts	readonly number[]

Returns

(count) => 0 | 1 | 2 | 3 | 4

---

hourLabel()

hourLabel(hour): string

Hour label follows the User’s selected time format.

Parameters

Parameter	Type
hour	number

Returns

string

---

hourLabelFadeMinutes()

hourLabelFadeMinutes(hourHeightPx, scale?): number

Hide an hour label only when its on-screen box meets the now pill. Caption text is 12 px at scale 1 (--text-caption-base in tokens.css); the pill adds about 2 px of vertical padding and normal line-height, then a 4 px gap keeps the two labels from crowding. Keep this in pixels so zooming the hour does not make the fade zone grow in minutes.

Parameters

Parameter	Type
hourHeightPx	number
scale?	number

Returns

number

---

inlineAudioClock()

inlineAudioClock(key): string

The Compact clock for one key: “0:12 / 1:05” while it owns the player and the length is decoded, otherwise empty. The length is known only after a play or seek, because rows never prefetch audio.

Parameters

Parameter	Type
key	string | null | undefined

Returns

string

---

inlineAudioView()

inlineAudioView(key): InlineAudioView

Read the shared state for one key; other keys see an idle player.

Parameters

Parameter	Type
key	string | null | undefined

Returns

InlineAudioView

---

instantForLocalDateTime()

instantForLocalDateTime(date, clock, timeZone): Date

Convert a User-zone local day and clock to the matching UTC instant.

Parameters

Parameter	Type
date	string
clock	string
timeZone	string

Returns

Date

---

isCalendarView()

isCalendarView(value): value is CalendarView

Parameters

Parameter	Type
value	string

Returns

value is CalendarView

---

isDarkTheme()

isDarkTheme(id): boolean

Parameters

Parameter	Type
id	ThemeId

Returns

boolean

---

isoWeek()

isoWeek(date): number

ISO-8601 week number (1..53). The ISO week belongs to the year that owns its Thursday; weeks start on Monday. Standard algorithm, computed from a local-naive date so it matches what the user sees.

Parameters

Parameter	Type
date	string

Returns

number

---

isSolarDaylight()

isSolarDaylight(instant, coordinates, timeZone): boolean

Return true while the sun is above the apparent sunrise horizon.

Parameters

Parameter	Type
instant	number
coordinates	SolarCoordinates
timeZone	string

Returns

boolean

---

isThemeFamilyId()

isThemeFamilyId(value): value is ThemeFamilyId

Parameters

Parameter	Type
value	unknown

Returns

value is ThemeFamilyId

---

isThemeId()

isThemeId(value): value is ThemeId

Parameters

Parameter	Type
value	unknown

Returns

value is ThemeId

---

isValidDate()

isValidDate(s): boolean

Returns true if s is a structurally and calendrically valid YYYY-MM-DD. The regex rejects non-date shapes; the real-date round-trip rejects February-30, April-31, etc. (Date() normalises those to the next month). Used by the deep-link intent parser to reject malformed /d/<date> params before they cause a silent no-op or a misleading “no entries” announce.

Parameters

Parameter	Type
s	string

Returns

boolean

---

isVoiceMemoPath()

isVoiceMemoPath(target): boolean

.webm is ambiguous to extension-only MIME guessers: recorded audio uses that container, while the generic guess is video/webm. The designated Voice memos folder and recorder extensions retain the audio meaning for Calendar cards until Files stores the upload’s actual media type.

Parameters

Parameter	Type
target	string

Returns

boolean

---

itemRepresentationKind()

itemRepresentationKind(kind, name, mediaType?): "log" | "task" | "note" | "file" | "photo" | "link" | "video" | "document" | "mail" | "folder" | "voice"

Map real item metadata into one presentation kind; text identities win over thumbnails (#822).

Parameters

Parameter	Type
kind	string
name	string
mediaType?	string | null

Returns

"log" | "task" | "note" | "file" | "photo" | "link" | "video" | "document" | "mail" | "folder" | "voice"

---

itemSlots()

itemSlots(items, minutes?): ItemSlot[]

Standalone items (issue #589) grouped by kind into fixed intervals. Photos added on one date form one deck even when their upload timestamps differ; captured Photos remain grouped near their captured time. Items in one deck are newest first. GridColumn derives the square’s layout interval from zoom; this grouping stays stable while that interval changes.

Parameters

Parameter	Type
items	readonly GridItem[]
minutes?	number

Returns

ItemSlot[]

---

layoutColumns()

layoutColumns<T>(items): Placed<T>[]

Apple-style side-by-side layout: items that overlap in time form a cluster, each item takes the first free column in its cluster, and every item in the cluster shares the cluster’s column count so widths line up. layoutEnd may extend a short card to its minimum drawn title line without changing its actual end; at midnight the floor grows upward so it stays inside the day. Neighbouring cards pack against this visual interval (#384, #469, DESIGN §39).

Type Parameters

Type Parameter
T extends object

Parameters

Parameter	Type
items	readonly T[]

Returns

Placed<T>[]

---

layoutPlanActual()

layoutPlanActual<E, L, A>(events, logs, minimumDurationMinutes?, activities?): object

Plan beside actual and activity decks, only where they overlap (Apple’s overlap layout with a Toggl-style twist). Items form clusters of transitive time overlap; a cluster with one item keeps the full column width. Inside a cluster, events (plan) take the left columns. Logs and activity decks share the actual side and pack into the first free lane, so either takes space only while another participant actually overlaps it. layoutStart and layoutEnd describe visual occupancy, including an upward floor at midnight; start and end stay the real times for labels and status (DESIGN §39, #384, #469).

Type Parameters

Type Parameter	Default type
E extends object	-
L extends object	-
A extends object	never

Parameters

Parameter	Type
events	readonly E[]
logs	readonly L[]
minimumDurationMinutes?	number
activities?	readonly A[]

Returns

object

Name	Type
activities	Placed<A>[]
events	Placed<E>[]
logs	Placed<L>[]

---

localDate()

localDate(d?): string

Local-naive YYYY-MM-DD for a Date.

Parameters

Parameter	Type
d?	Date

Returns

string

---

lodTier()

lodTier(height, current): 1 | 2 | 3

The tier for height, given the current tier (0 when there is none yet).

Parameters

Parameter	Type
height	number
current	number

Returns

1 | 2 | 3

---

logEntryHref()

logEntryHref(date, id): string

A log entry’s stable link: its day plus its block anchor.

Parameters

Parameter	Type
date	string
id	string | null

Returns

string

---

minimumGridDurationMinutes()

minimumGridDurationMinutes(hourHeightPx): number

Minimum duration that yields one caption title line at the chosen zoom. Caption is 12 px, line-height is 1.25, vertical padding totals 6 px, and the block stack gap is 2.5 px (tokens.css and GridColumn). UI scale cancels from both pixel terms and hour height. Layout packs against this visual end while labels keep the Log’s real end (#384, DESIGN §39).

Parameters

Parameter	Type
hourHeightPx	number

Returns

number

---

monthGrid()

monthGrid(date, firstDay): string[]

The 42 dates (six weeks) a month page shows, first weekday first.

Parameters

Parameter	Type
date	string
firstDay	WeekDay

Returns

string[]

---

motionDurationMs()

motionDurationMs(milliseconds, reducedMotion?): number

Resolve a shared duration, preserving the same timing for every input modality (#611).

Parameters

Parameter	Type
milliseconds	number
reducedMotion?	boolean

Returns

number

---

movedEnd()

movedEnd(entry, start): string | null

The end of an entry moved to start (minutes). The entry keeps its real length, so a range across midnight stays one (#99) although the grid draws it only to midnight. A point entry has no end.

Parameters

Parameter	Type
entry	{ end: string | null; start: string; }
entry.end	string | null
entry.start	string
start	number

Returns

string | null

---

nearestIndex()

nearestIndex(scrollLeft, columnWidth): number

The nearest column edge for a released scroll (the snap target).

Parameters

Parameter	Type
scrollLeft	number
columnWidth	number

Returns

number

---

nextSolarBoundary()

nextSolarBoundary(instant, coordinates, timeZone): SolarBoundary | null

Find the next sunrise or sunset which changes the current colour scheme.

Parameters

Parameter	Type
instant	number
coordinates	SolarCoordinates
timeZone	string

Returns

SolarBoundary | null

---

normalizeDateTimePreferences()

normalizeDateTimePreferences(value): DateTimePreferences

Keep unknown settings from a newer or hand-edited settings file harmless.

Parameters

Parameter	Type
value	unknown

Returns

DateTimePreferences

---

normalizeWheelDelta()

normalizeWheelDelta(event, linePx?, pagePx?): WheelDelta

Convert a WheelEvent-like value to pixel-equivalent units. The defaults are intentionally conservative browser conventions (16px per line and an 800px page); the action supplies its measured viewport width for page-mode input. Non-finite deltas are treated as zero so malformed synthetic events cannot arm a gesture.

Parameters

Parameter	Type
event	Pick<WheelEvent, "deltaX" | "deltaY" | "deltaMode">
linePx?	number
pagePx?	number

Returns

WheelDelta

---

noteHref()

noteHref(id): string

A note’s stable link: its calternal-id, never its path (DESIGN §33).

Parameters

Parameter	Type
id	string

Returns

string

---

nowMinutes()

nowMinutes(now?): number

Parameters

Parameter	Type
now?	Date

Returns

number

---

officeFileLabel()

officeFileLabel(_name, mime?): string | null

Give indexed Office MIME types a short label when no page thumbnail is available.

Parameters

Parameter	Type
_name	string
mime?	string | null

Returns

string | null

---

opensCalendarItemDirectly()

opensCalendarItemDirectly(event): boolean

Detect keyboard, touch and double-click opens for standalone Calendar items (#1115, DESIGN §34).

Parameters

Parameter	Type
event	MouseEvent

Returns

boolean

---

originFor()

originFor(date): string

Parameters

Parameter	Type
date	string

Returns

string

---

overlapLaneCapacity()

overlapLaneCapacity(columnWidth, minimumLaneWidth, scale?, reservesMore?): number

Return how many overlap lanes fit without shrinking below their declared width. The math mirrors GridColumn’s 8 px edge insets, 2 px lane gap and, when present, 34 px reserved More pill; it uses no text or DOM measurements (DESIGN §39, #427, #969).

Parameters

Parameter	Type
columnWidth	number
minimumLaneWidth	number
scale?	number
reservesMore?	boolean

Returns

number

---

overlapLaneWidth()

overlapLaneWidth(columnWidth, laneCount, scale?, reservesMore?): number

Return the actual block width produced by GridColumn’s lane CSS, including the More pill reservation for overflow clusters (#427, #969).

Parameters

Parameter	Type
columnWidth	number
laneCount	number
scale?	number
reservesMore?	boolean

Returns

number

---

paletteForAppearance()

paletteForAppearance(mode, lightPalette, darkPalette, systemDark): ThemeId

Resolve a legacy pair while old local settings migrate to a theme family.

Parameters

Parameter	Type
mode	"system" | "light" | "dark"
lightPalette	ThemeId
darkPalette	ThemeId
systemDark	boolean

Returns

ThemeId

---

paletteForFamily()

paletteForFamily(family, scheme, variants?): ThemeId

Resolve a family palette, applying its remembered dark variant if present.

Parameters

Parameter	Type
family	ThemeFamilyId
scheme	"light" | "dark"
variants?	Partial<ThemeVariantSelections>

Returns

ThemeId

---

paletteForMode()

paletteForMode(mode, selected, systemDark): ThemeId

Pick a legacy theme for an old saved system, light, or dark appearance.

Parameters

Parameter	Type
mode	"system" | "light" | "dark"
selected	ThemeId
systemDark	boolean

Returns

ThemeId

---

panelWidthProperty()

panelWidthProperty(id): string

Parameters

Parameter	Type
id	string

Returns

string

---

parseDate()

parseDate(date): Date

Parameters

Parameter	Type
date	string

Returns

Date

---

parseTooltipKeys()

parseTooltipKeys(value): KbdKey[]

Reads a data-tooltip-keys value back into a combo.

Parameters

Parameter	Type
value	string | null | undefined

Returns

KbdKey[]

---

pauseInlineAudioPlayback()

pauseInlineAudioPlayback(): void

Stop the current sound but retain its elapsed position for the visible chip.

Returns

void

---

pauseInlineAudioPlaybackFor()

pauseInlineAudioPlaybackFor(key): void

Pause only when key owns the player, so one surface cannot stop another’s sound.

Parameters

Parameter	Type
key	string

Returns

void

---

photoHref()

photoHref(id): string

A photo opens in the Photos viewer over its day (DESIGN §33 /p/<item-id>).

Parameters

Parameter	Type
id	string

Returns

string

---

pinchMetrics()

pinchMetrics(a, b): object

One geometry contract for touch pinch owners. Each surface chooses its own zoom bounds and whether a discrete density step or continuous scale fits.

Parameters

Parameter	Type
a	{ x: number; y: number; }
a.x	number
a.y	number
b	{ x: number; y: number; }
b.x	number
b.y	number

Returns

object

Name	Type
distance	number
x	number
y	number

---

placeBeside()

placeBeside(rect, size, gap?, viewport?, margin?): { left: number; side: "left" | "right"; top: number; } | null

Beside the anchor (Finder’s Get Info next to the selected item): right of it when the surface fits, else left of it, top-aligned with the anchor and clamped into the viewport. Null when neither side has room (a full-width row on a phone); the caller then falls back to below/above placement.

Parameters

Parameter	Type
rect	{ left: number; right: number; top: number; }
rect.left	number
rect.right	number
rect.top?	number
size?	{ h: number; w: number; }
size.h?	number
size.w?	number
gap?	number
viewport?	{ h: number; w: number; }
viewport.h?	number
viewport.w?	number
margin?	number

Returns

{ left: number; side: "left" | "right"; top: number; } | null

---

placeNearPoint()

placeNearPoint(point, size, options?): NearPointResult

Place a floating surface beside a point, preferring its right side and opening left when the right side does not fit. Below placement flips above the point when needed, then the shared viewport rule clamps every edge. The centre mode keeps chart readouts beside their datum while sharing the same horizontal flip and bounds logic (#421, #504).

Parameters

Parameter	Type
point	{ x: number; y: number; }
point.x	number
point.y	number
size?	{ h: number; w: number; }
size.h?	number
size.w?	number
options?	NearPointOptions

Returns

NearPointResult

---

placeTooltip()

placeTooltip(trigger, bubble, viewport, side?, obstacles?): TooltipPlacement

Centres the bubble on the trigger, below it by default. It goes above when side asks for it or when there is no room below (the bottom mode tray), and it is clamped inside the viewport. When a caller supplies nearby controls, it tries alternate horizontal and vertical lanes so the tooltip does not hide them.

Parameters

Parameter	Type
trigger	Box
bubble	{ height: number; width: number; }
bubble.height	number
bubble.width	number
viewport?	{ height: number; width: number; }
viewport.height?	number
viewport.width?	number
side?	"top" | "bottom" | null
obstacles?	readonly Box[]

Returns

TooltipPlacement

---

placeWithinViewport()

placeWithinViewport(anchor, size, opts?): PlaceResult

Compute a viewport-clamped { top, left } for a floating element so it never clips outside the visible area.

anchor.y is the hinge shared by both directions: opening down → element top edge = anchor.y opening up → element bottom edge = anchor.y → top = anchor.y − size.h

Callers should pass the natural “just below the trigger” coordinate (e.g. button.bottom + gap) and let this function flip direction automatically when there is not enough room below.

Parameters

Parameter	Type
anchor	{ x: number; y: number; }
anchor.x	number
anchor.y	number
size?	{ h: number; w: number; }
size.h?	number
size.w?	number
opts?	PlaceOptions

Returns

PlaceResult

Examples

— ⋯ button, right-aligned menu:
  const r = btn.getBoundingClientRect();
  const { top, left, placement } = placeWithinViewport(
    { x: r.right - menuWidth, y: r.bottom + 6 },
    { w: menuWidth, h: menuHeight },
  );

— Long-press at pointer coords:
  const { top, left } = placeWithinViewport(
    { x: pointerX, y: pointerY },
    { w: menuWidth, h: menuHeight },
  );

---

portal()

portal(node, enabled?): object

Move a whole Svelte branch into the shared overlay layer.

Parameters

Parameter	Type
node	HTMLElement
enabled?	boolean

Returns

object

Name	Type
destroy()	() => void
update()	(next) => void

---

portalTarget()

portalTarget(): HTMLElement | null

Return the shared mount target for framework portals such as React charts.

Returns

HTMLElement | null

---

previewAnchor()

previewAnchor(node, item): object

Svelte action: register item for this card while it is mounted.

Parameters

Parameter	Type
node	HTMLElement
item	PreviewItem

Returns

object

Name	Type
destroy()	() => void
update()	(next) => void

---

previewForAnchor()

previewForAnchor(node): PreviewItem | null

The item a registered card shows, or null for any other element.

Parameters

Parameter	Type
node	Element

Returns

PreviewItem | null

---

pullActionOutcome()

pullActionOutcome(offset, refreshThreshold, updateThreshold): PullActionOutcome

Choose the short-pull refresh or longer update action from the distance the User saw. A pull below the first threshold cancels; update always wins after its second threshold, including when the current build already matches.

Parameters

Parameter	Type
offset	number
refreshThreshold	number
updateThreshold	number

Returns

PullActionOutcome

---

pullDistance()

pullDistance(raw, max, reduced?): number

Rubber-band the raw downward finger travel into an indicator offset. We damp progressively (sub-linear) so the pull feels elastic and resists going far — a constant ratio would feel like the content is just glued to the finger.

raw is the downward travel in px (negative/zero ⇒ no pull, returns 0). The damping uses a square-root-ish curve normalized to max so travel approaches but never blows past max. With reduced (prefers-reduced-motion) we skip the elastic curve and clamp linearly to max — no springy overscroll feel, but the gesture still works and the indicator still tracks the finger.

Parameters

Parameter	Type
raw	number
max	number
reduced?	boolean

Returns

number

---

pullDown()

pullDown(node, opts?): object

Svelte action: pull-down-from-top. Dependency-free, same style as swipe (raw Pointer Events, pure decision helpers). The action is purely a GESTURE DETECTOR — it owns no indicator/aria; it emits onmove/oncommit/oncancel and the consumer renders any affordance.

Why it lives on a wrapper node (not window): attaching to the scroll container keeps it scoped and lets overscroll-behavior: contain on #route-content suppress page chaining so our rubber-band is the only one (#718). We arm the gesture ONLY when the drag begins at scroll-top, within the top band (when bandPx is set), or on an explicit allowAwayFromTop surface, AND the first locked axis is a downward ‘y’ — an upward drag, or any mostly-horizontal drag (e.g. the date strip’s own horizontal scroll), is left entirely to the native scroller (we never preventDefault those).

Parameters

Parameter	Type
node	HTMLElement
opts?	PullDownOpts

Returns

object

Name	Type
destroy()	() => void
update()	(next) => void

---

pullOutcome()

pullOutcome(offset, threshold): PullOutcome

Decide whether a release commits a refresh. Commits only when the (already rubber-banded) indicator offset reached the threshold. Anything shorter snaps back. Kept separate from pullDistance so the threshold is checked against what the user actually saw travel, not the raw finger delta.

Parameters

Parameter	Type
offset	number
threshold	number

Returns

PullOutcome

---

readPanelWidth()

readPanelWidth(id, fallback, min, max): number

Read a panel width from this Installation’s local storage (#901, owner resizable-panel rule). Clamp finite saved values to the caller’s bounds; missing, invalid or unavailable storage returns the supplied fallback.

Parameters

Parameter	Type
id	string
fallback	number
min	number
max	number

Returns

number

---

recentreShift()

recentreShift(first, visible): number

Days to shift the origin by after a settled scroll, or 0.

Parameters

Parameter	Type
first	number
visible	number

Returns

number

---

releaseAudioFocus()

releaseAudioFocus(owner): void

Forget a foreign element that left the page, so it is never paused late.

Parameters

Parameter	Type
owner	{ pause: void; }
owner.pause

Returns

void

---

renderWindow()

renderWindow(first, visible, buffer): object

The columns to render: the visible ones plus buffer on each side. Off-screen buffer columns use content-visibility: auto, so they cost DOM, not paint.

Parameters

Parameter	Type
first	number
visible	number
buffer	number

Returns

object

Name	Type
end	number
start	number

---

representationCounts()

representationCounts(attachments): object[]

Count each presentation kind once for a short card’s meta line (#822).

Parameters

Parameter	Type
attachments	readonly CalendarAttachment[]

Returns

object[]

---

resizableEdge()

resizableEdge(node, initialOptions): object

Attach pointer and keyboard resizing to an invisible separator (#901). Coalesce drag writes into one animation frame and persist committed widths. Collapse calls the caller without overwriting the last expanded width; double-click resets it. Destroy removes listeners and cancels a queued frame.

Parameters

Parameter	Type
node	HTMLElement
initialOptions	ResizableEdgeOptions

Returns

object

Name	Type
destroy()	() => void
update()	(next) => void

---

resolveAxis()

resolveAxis(dx, dy, tol): Axis | null

Decide the locked axis once movement exceeds the tolerance. Returns null while still within the dead zone. Ties (|dx| === |dy|) resolve to ‘y’ so an ambiguous drag favors page scroll over a swipe (never hijack the scroll).

Parameters

Parameter	Type
dx	number
dy	number
tol	number

Returns

Axis | null

---

resolveDefaultTheme()

resolveDefaultTheme(): ThemeId

Returns

ThemeId

---

resolveTimeSnap()

resolveTimeSnap(input): object

Resolve one edit edge to item boundaries, Now, then the grid step. The six-pixel magnetic band scales with zoom and caps at five minutes so a short hour does not make a wide part of the day feel sticky (#536). Create endpoints also clamp out of item interiors, and keyboard steps stop at a crossed boundary so a non-grid edge is never skipped (#714, §57). short hour does not make a wide part of the day feel sticky. Item edges are sorted by minute/key/edge when the day changes, so each pointer update finds its narrow candidate range with binary search. The resolver expands minute groups outward from the pointer, so an exact match returns after the first eligible edge instead of scanning a dense equal-time group (#751, #536).

Parameters

Parameter	Type
input	CalendarSnapInput

Returns

object

Name	Type
minute	number
target	CalendarSnapTarget

---

resolveWheelAxis()

resolveWheelAxis(dx, dy, tol?, dominance?): Axis | null

Lock a wheel sequence only when horizontal movement clearly dominates. A trackpad often emits a small vertical component beside a horizontal swipe; requiring a ratio keeps that diagonal input in the page scroller. Ties and mostly-vertical movement resolve to y, matching resolveAxis’s scroll-first rule. tol is applied to the accumulated sequence, not one event.

Parameters

Parameter	Type
dx	number
dy	number
tol?	number
dominance?	number

Returns

Axis | null

---

scrollLeftForIndex()

scrollLeftForIndex(index, columnWidth): number

The scroll offset for a settled day index at the current column width.

Parameters

Parameter	Type
index	number
columnWidth	number

Returns

number

---

seekInlineAudioPlayback()

seekInlineAudioPlayback(key, source, seconds): void

Seek key to seconds. A key that does not own the player loads it paused at that position, so dragging a timeline never starts sound.

Parameters

Parameter	Type
key	string
source	string | undefined
seconds	number

Returns

void

---

setCalendarTimeZoneOverride()

setCalendarTimeZoneOverride(timeZone): void

Apply a time zone the User confirmed after travel detection.

Parameters

Parameter	Type
timeZone	string | null

Returns

void

---

setCalendarWindow()

setCalendarWindow(window, anchor, span?): void

Update the anchor and span through one operation for each navigation.

Parameters

Parameter	Type
window	CalendarWindow
anchor	string
span?	number

Returns

void

---

setInlineAudioRate()

setInlineAudioRate(rate): void

Set the shared playback speed; it also applies to the next sound.

Parameters

Parameter	Type
rate	number

Returns

void

---

sheetDismiss()

sheetDismiss(distance, velocity, threshold?): boolean

A downward sheet drag commits by travel or a deliberate fling. Velocity is in px/s, the same unit returned by createInteractiveSpring. A reverse fling always returns the sheet, even after it crossed the distance threshold.

Parameters

Parameter	Type
distance	number
velocity	number
threshold?	number

Returns

boolean

---

sheetSnap()

sheetSnap(offset, width, velocity): "open" | "closed"

The edge-swipe sidebar sheet (owner, 2026-09-25): where a released drag settles. offset is the sheet’s translateX (0 = open, -width = closed), velocity px/ms (positive = toward open). A fling decides first (more than 0.5 px/ms either way); otherwise the sheet goes where more than half of it is.

Parameters

Parameter	Type
offset	number
width	number
velocity	number

Returns

"open" | "closed"

---

shouldFadeHourLabel()

shouldFadeHourLabel(nowMinutes, hour, hourHeightPx, scale?): boolean

The pure geometry model of TimeGrid’s CSS mask around the now pill.

Parameters

Parameter	Type
nowMinutes	number
hour	number
hourHeightPx	number
scale?	number

Returns

boolean

---

shouldShowTimeZoneChip()

shouldShowTimeZoneChip(timezone, userZone?): timezone is string

Hide a zone that matches this User’s device zone, as Calendar previews do.

Parameters

Parameter	Type
timezone	string | null | undefined
userZone?	string

Returns

timezone is string

---

solarEventsForDate()

solarEventsForDate(year, month, day, coordinates, timeZone): SolarEvents

Calculate the apparent sunrise and sunset for one local calendar date.

Parameters

Parameter	Type
year	number
month	number
day	number
coordinates	SolarCoordinates
timeZone	string

Returns

SolarEvents

---

splitCalendarTimeRange()

splitCalendarTimeRange(startDate, start, endDate, end): CalendarTimePart[]

Split a positive timed range into local-day parts without treating a day as 24 elapsed hours. The Calendar stores local date keys, so date stepping stays correct across daylight-saving changes (#469, DESIGN §30 C12). Callers use this only for bounded Calendar ranges; larger event spans use calendarTimePartForDay to ask for the one visible part they need.

Parameters

Parameter	Type
startDate	string
start	string
endDate	string
end	string

Returns

CalendarTimePart[]

---

startOfMonth()

startOfMonth(date): string

Parameters

Parameter	Type
date	string

Returns

string

---

startOfWeek()

startOfWeek(date, firstDay): string

The first day of the week that contains date. Same rule as the core’s analyticsPeriodRange('week', date, firstDay).start (see the file header for why it is repeated here).

Parameters

Parameter	Type
date	string
firstDay	WeekDay

Returns

string

---

stepDate()

stepDate(view, date, delta): string

Move one page in a view: a day, a week, a month or a year.

Parameters

Parameter	Type
view	CalendarView
date	string
delta	number

Returns

string

---

swipe()

swipe(node, opts?): object

Parameters

Parameter	Type
node	HTMLElement
opts?	SwipeOpts

Returns

object

Name	Type
destroy()	() => void
update()	(next) => void

---

swipeOutcome()

swipeOutcome(axisLocked, dx, leftThreshold, rightThreshold): SwipeOutcome

Resolve what a release means given the locked axis + travel. Left and right can use different commit thresholds (the destructive direction wants a larger one — H1). A non-x axis or a drag that never locked yields ‘none’.

Parameters

Parameter	Type
axisLocked	Axis | null
dx	number
leftThreshold	number
rightThreshold	number

Returns

SwipeOutcome

---

systemLocale()

systemLocale(): string

A localized name for the browser’s current system locale and time zone.

Returns

string

---

systemTimeZone()

systemTimeZone(): string

Returns

string

---

tagColor()

tagColor(tag, overrides?): TagColor

Resolve a tag’s color. overrides maps tag -> a hex/oklch foreground; when present we derive a soft bg from it via color-mix so user picks stay legible.

Parameters

Parameter	Type
tag	string
overrides?	Record<string, string>

Returns

TagColor

---

tagHref()

tagHref(tag): string

A tag page. /tags/<tag> still redirects here for older links.

Parameters

Parameter	Type
tag	string

Returns

string

---

taskHref()

taskHref(id): string

Parameters

Parameter	Type
id	string

Returns

string

---

themeDef()

themeDef(id): ThemeDef

Parameters

Parameter	Type
id	ThemeId

Returns

ThemeDef

---

themeFamilyDef()

themeFamilyDef(id): ThemeFamilyDef

Parameters

Parameter	Type
id	ThemeFamilyId

Returns

ThemeFamilyDef

---

timezoneCity()

timezoneCity(timeZone): TimezoneCity | null

Resolve a browser IANA zone, including a legacy name, to its reference city.

Parameters

Parameter	Type
timeZone	string

Returns

TimezoneCity | null

---

timeZoneDateTimeFormatter()

timeZoneDateTimeFormatter(timeZone, locale?): DateTimeFormat

Return shared cached numeric parts for solar math and Calendar Event edits. h23 keeps Calendar wall time in the 00:00–23:59 grammar so editing preserves the Event’s zone and date (#421; DESIGN §34).

Parameters

Parameter	Type
timeZone	string
locale?	LocalesArgument

Returns

DateTimeFormat

---

tip()

tip(label, shortcut?, side?, icon?): TooltipAttributes

Attributes that give a control the warm tooltip. side forces a side; without it the bubble goes below the control, or above it when there is no room (the bottom mode tray). icon names a small decorative icon; the trigger keeps its own accessible name.

Parameters

Parameter	Type
label	string
shortcut?	any
side?	"top" | "bottom"
icon?	TooltipIconName

Returns

TooltipAttributes

---

toCells()

toCells(dates, today?, firstDay?): StripCell[]

Map a range of date strings to fully-decorated strip cells.

Parameters

Parameter	Type
dates	string[]
today?	string
firstDay?	WeekDay

Returns

StripCell[]

---

toggleInlineAudioPlayback()

toggleInlineAudioPlayback(key, source?): Promise<void>

Toggle one sound; a new key pauses the previous file before it starts.

Parameters

Parameter	Type
key	string
source?	string

Returns

Promise<void>

---

toMinutes()

toMinutes(time): number

HH:MM → minutes after midnight (NaN-safe: bad input is 0).

Parameters

Parameter	Type
time	string

Returns

number

---

tooltipCombo()

tooltipCombo(shortcut): readonly KbdKey[] | null

Parameters

Parameter	Type
shortcut	any

Returns

readonly KbdKey[] | null

---

userLocale()

userLocale(): string | undefined

The locale used by System date and week preferences. A custom date order or hour cycle does not change the language used for names; outside a browser (SSR, unit tests) this is undefined, which means the Intl default locale. Keep one accessor so a future language setting changes one line.

Returns

string | undefined

---

viewDates()

viewDates(view, date, firstDay): string[]

The dates a view needs data for.

Parameters

Parameter	Type
view	CalendarView
date	string
firstDay	WeekDay

Returns

string[]

---

viewStart()

viewStart(view, date, firstDay?): string

The date a view opens on when the user asks for “the week (or day) of date” (Today, a view switch, the app’s entry). The Week view’s path date is its first visible day (DESIGN §39: Week can rest on any 7-day window, and a link restores that exact window), so “the week of” starts on the locale’s first weekday. Other views keep the date.

Parameters

Parameter	Type
view	CalendarView
date	string
firstDay?	WeekDay

Returns

string

---

viewTitle()

viewTitle(view, date): object

Label the view from its visible anchor. A Week that crosses a month or year names both endpoints so the title cannot suggest a different date window (#609, DESIGN §§33, 34).

Parameters

Parameter	Type
view	CalendarView
date	string

Returns

object

Name	Type
rest	string
short	string
strong	string
sub	string

---

weekDates()

weekDates(date, firstDay): string[]

The seven dates of the week that contains date, first day first.

Parameters

Parameter	Type
date	string
firstDay	WeekDay

Returns

string[]

---

weekStartDay()

weekStartDay(locale?): WeekDay

First day of the week for locale (default: userLocale()).

Order: a product override for the region (WEEK_START_OVERRIDES) → the engine’s CLDR week info (getWeekInfo(), or the older weekInfo getter; both report 1 = Monday … 7 = Sunday) → the region table above → Monday. The region uses maximize(), so a bare language such as en resolves to its likely region. An invalid locale string falls back to Monday rather than throwing.

Parameters

Parameter	Type
locale?	string

Returns

WeekDay

---

wheelZoomFactor()

wheelZoomFactor(deltaY, deltaMode?): number

The zoom factor for one wheel event with Ctrl or Cmd held. A trackpad pinch arrives as many small ctrlKey wheel deltas; a mouse wheel notch is about 100 px. The clamp keeps one notch near a 1.3× step, and exp() makes a zoom in and the same zoom out cancel exactly.

Parameters

Parameter	Type
deltaY	number
deltaMode?	number

Returns

number

References

ItemChip

Renames and re-exports ItemCard

---

Menu

Re-exports Menu