From 7949fcdc683d07689bad5da5d20bfa3eeb5a6a46 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= Date: Tue, 5 Sep 2023 01:25:00 +0200 Subject: Move frontend code to subdirectories, to simplify command line flags. --- static/ts/types.ts | 208 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 208 insertions(+) create mode 100644 static/ts/types.ts (limited to 'static/ts/types.ts') diff --git a/static/ts/types.ts b/static/ts/types.ts new file mode 100644 index 00000000..64e2c709 --- /dev/null +++ b/static/ts/types.ts @@ -0,0 +1,208 @@ +export { + ical_type, + valid_input_types, + JCalProperty, JCal, + xcal, uid, + ChangeLogEntry +} + +let all_types = [ + 'text', + 'uri', + 'binary', + 'float', /* Number.type = 'float' */ + 'integer', /* Number.type = 'integer' */ + 'date-time', /* Date */ + 'date', /* Date.dateonly = true */ + 'duration', /* TODO */ + 'period', /* TODO */ + 'utc-offset', /* TODO */ + 'cal-address', + 'recur', /* RRule */ + 'boolean', /* boolean */ +] + + +type ical_type + = 'text' + | 'uri' + | 'binary' + | 'float' + | 'integer' + | 'date-time' + | 'date' + | 'duration' + | 'period' + | 'utc-offset' + | 'cal-address' + | 'recur' + | 'boolean' + | 'unknown' + +let property_names = [ + 'calscale', 'method', 'prodid', 'version', 'attach', 'categories', + 'class', 'comment', 'description', 'geo', 'location', 'percent-complete', + 'priority', 'resources', 'status', 'summary', 'completed', 'dtend', 'due', + 'dtstart', 'duration', 'freebusy', 'transp', 'tzid', 'tzname', 'tzoffsetfrom', + 'tzoffsetto', 'tzurl', 'attendee', 'contact', 'organizer', 'recurrence-id', + 'related-to', 'url', 'uid', 'exdate', 'exrule', 'rdate', 'rrule', 'action', + 'repeat', 'trigger', 'created', 'dtstamp', 'last-modified', 'sequence', 'request-status' +]; + + +let valid_fields: Map = new Map([ + ['VCALENDAR', ['PRODID', 'VERSION', 'CALSCALE', 'METHOD']], + ['VEVENT', ['DTSTAMP', 'UID', 'DTSTART', 'CLASS', 'CREATED', + 'DESCRIPTION', 'GEO', 'LAST-MODIFIED', 'LOCATION', + 'ORGANIZER', 'PRIORITY', 'SEQUENCE', 'STATUS', + 'SUMMARY', 'TRANSP', 'URL', 'RECURRENCE-ID', + 'RRULE', 'DTEND', 'DURATION', 'ATTACH', 'ATTENDEE', + 'CATEGORIES', 'COMMENT', 'CONTACT', 'EXDATE', + 'REQUEST-STATUS', 'RELATED-TO', 'RESOURCES', 'RDATE']], + ['VTODO', ['DTSTAMP', 'UID', 'CLASS', 'COMPLETED', 'CREATED', + 'DESCRIPTION', 'DTSTART', 'GEO', 'LAST-MODIFIED', + 'LOCATION', 'ORGANIZER', 'PERCENT-COMPLETE', 'PRIORITY', + 'RECURRENCE-ID', 'SEQUENCE', 'STATUS', 'SUMMARY', 'URL', + 'RRULE', 'DUE', 'DURATION', 'ATTACH', 'ATTENDEE', 'CATEGORIES', + 'COMMENT', 'CONTACT', 'EXDATE', 'REQUEST-STATUS', 'RELATED-TO', + 'RESOURCES', 'RDATE',]], + ['VJOURNAL', ['DTSTAMP', 'UID', 'CLASS', 'CREATED', 'DTSTART', 'LAST-MODIFIED', + 'ORGANIZER', 'RECURRENCE-ID', 'SEQUENCE', 'STATUS', 'SUMMARY', + 'URL', 'RRULE', 'ATTACH', 'ATTENDEE', 'CATEGORIES', 'COMMENT', + 'CONTACT', 'DESCRIPTION', 'EXDATE', 'RELATED-TO', 'RDATE', + 'REQUEST-STATUS']], + ['VFREEBUSY', ['DTSTAMP', 'UID', 'CONTACT', 'DTSTART', 'DTEND', + 'ORGANIZER', 'URL', 'ATTENDEE', 'COMMENT', 'FREEBUSY', + 'REQUEST-STATUS']], + ['VTIMEZONE', ['TZID', 'LAST-MODIFIED', 'TZURL']], + ['VALARM', ['ACTION', 'TRIGGER', 'DURATION', 'REPEAT', 'ATTACH', + 'DESCRIPTION', 'SUMMARY', 'ATTENDEE']], + ['STANDARD', ['DTSTART', 'TZOFFSETFROM', 'TZOFFSETTO', 'RRULE', + 'COMMENT', 'RDATE', 'TZNAME']], +]) + +valid_fields.set('DAYLIGHT', valid_fields.get('STANDARD')!); + +type known_ical_types + = 'ACTION' + | 'ATTACH' + | 'ATTENDEE' + | 'CALSCALE' + | 'CATEGORIES' + | 'CLASS' + | 'COMMENT' + | 'COMPLETED' + | 'CONTACT' + | 'CREATED' + | 'DESCRIPTION' + | 'DTEND' + | 'DTSTAMP' + | 'DTSTART' + | 'DUE' + | 'DURATION' + | 'EXDATE' + | 'FREEBUSY' + | 'GEO' + | 'LAST-MODIFIED' + | 'LOCATION' + | 'METHOD' + | 'ORGANIZER' + | 'PERCENT-COMPLETE' + | 'PRIORITY' + | 'PRODID' + | 'RDATE' + | 'RECURRENCE-ID' + | 'RELATED-TO' + | 'REPEAT' + | 'REQUEST-STATUS' + | 'RESOURCES' + | 'RRULE' + | 'SEQUENCE' + | 'STATUS' + | 'SUMMARY' + | 'TRANSP' + | 'TRIGGER' + | 'TZID' + | 'TZNAME' + | 'TZOFFSETFROM' + | 'TZOFFSETTO' + | 'TZURL' + | 'URL' + | 'VERSION' + +let valid_input_types: Map> = + new Map([ + ['ACTION', ['text']], // AUDIO|DISPLAY|EMAIL|*other* + ['ATTACH', ['uri', 'binary']], + ['ATTENDEE', ['cal-address']], + ['CALSCALE', ['text']], + ['CATEGORIES', [['text']]], + ['CLASS', ['text']], // PUBLIC|PRIVATE|CONFIDENTIAL|*other* + ['COMMENT', ['text']], + ['COMPLETED', ['date-time']], + ['CONTACT', ['text']], + ['CREATED', ['date-time']], + ['DESCRIPTION', ['text']], + ['DTEND', ['date', 'date-time']], + ['DTSTAMP', ['date-time']], + ['DTSTART', ['date', 'date-time']], + ['DUE', ['date', 'date-time']], + ['DURATION', ['duration']], + ['EXDATE', [['date', 'date-time']]], + ['EXRULE', []], /* deprecated */ + ['FREEBUSY', [['period']]], + ['GEO', ['float']], // pair of floats + ['LAST-MODIFIED', ['date-time']], + ['LOCATION', ['text']], + ['METHOD', ['text']], + ['ORGANIZER', ['cal-address']], + ['PERCENT-COMPLETE', ['integer']], // 0-100 + ['PRIORITY', ['integer']], // 0-9 + ['PRODID', ['text']], + ['RDATE', [['date', 'date-time', 'period']]], + ['RECURRENCE-ID', ['date', 'date-time']], + ['RELATED-TO', ['text']], + ['REPEAT', ['integer']], + ['REQUEST-STATUS', ['text']], + ['RESOURCES', [['text']]], + ['RRULE', ['recur']], + ['SEQUENCE', ['integer']], + ['STATUS', ['text']], // see 3.8.1.11 + ['SUMMARY', ['text']], + ['TRANSP', ['text']], // OPAQUE|TRANSPARENT + ['TRIGGER', ['duration', 'date-time']], + ['TZID', ['text']], + ['TZNAME', ['text']], + ['TZOFFSETFROM', ['utc-offset']], + ['TZOFFSETTO', ['utc-offset']], + ['TZURL', ['uri']], + ['UID', ['text']], + ['URL', ['uri']], + ['VERSION', ['text']], + ]) + +// type JCalLine { +// } + +type tagname = 'vevent' | string + +type uid = string + +/* TODO is this type correct? + What really are valid values for any? Does that depend on ical_type? Why is the tail a list? + What really is the type for the parameter map? +*/ +type JCalProperty + = [string, Record, ical_type, any] + | [string, Record, ical_type, ...any[]] + +type JCal = [tagname, JCalProperty[], JCal[]] + +const xcal = "urn:ietf:params:xml:ns:icalendar-2.0"; + +interface ChangeLogEntry { + type: 'calendar' | 'property', + name: string, + from: string | null, + to: string | null, +} -- cgit v1.2.3 From f653a01328be3b8be6af35c0c96867623765ca5b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= Date: Tue, 5 Sep 2023 11:41:46 +0200 Subject: Move JS documentation into the JS-code. Texinfo was a bad match for how TypeScript is structured. This also allows generation of jsdoc pages, which can be nice. Another large win is that this opens up for the texinfo pages to replace the Guile heading with different subheadings, including - external library - internal library - C library - ... --- static/ts/types.ts | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) (limited to 'static/ts/types.ts') diff --git a/static/ts/types.ts b/static/ts/types.ts index 64e2c709..a0ab74a4 100644 --- a/static/ts/types.ts +++ b/static/ts/types.ts @@ -1,3 +1,8 @@ +/** + * Collection of type information for calendar data. + * @module + */ + export { ical_type, valid_input_types, @@ -6,6 +11,8 @@ export { ChangeLogEntry } + +/** Name of all valid icalendar types. */ let all_types = [ 'text', 'uri', @@ -23,6 +30,7 @@ let all_types = [ ] +/* The union of all elements in `all_types`. */ type ical_type = 'text' | 'uri' @@ -39,6 +47,10 @@ type ical_type | 'boolean' | 'unknown' +/** + * All known names properties (top level keys) can have. + * Such as "calscale", "dtstart", ... + */ let property_names = [ 'calscale', 'method', 'prodid', 'version', 'attach', 'categories', 'class', 'comment', 'description', 'geo', 'location', 'percent-complete', @@ -50,6 +62,15 @@ let property_names = [ ]; +/** + * Which property fields each component can hold. + * + * ```json + * { 'VCALENDAR': ['PRODID', 'VERSION', 'CALSCALE', 'METHOD'], + * ... + * } + * ``` + */ let valid_fields: Map = new Map([ ['VCALENDAR', ['PRODID', 'VERSION', 'CALSCALE', 'METHOD']], ['VEVENT', ['DTSTAMP', 'UID', 'DTSTART', 'CLASS', 'CREATED', @@ -130,6 +151,18 @@ type known_ical_types | 'URL' | 'VERSION' +/** + * Which types are valid to store under each property. + * If multiple values are an option for that property, then + * the list of possibilities will contain a sub-list (see example). + * + * ```json + * { 'DTSTART': ['date', 'date-time'], + * 'CATEGORIES': [['text']], + * ... + * } + * ``` + */ let valid_input_types: Map> = new Map([ ['ACTION', ['text']], // AUDIO|DISPLAY|EMAIL|*other* @@ -184,20 +217,35 @@ let valid_input_types: Map> = // type JCalLine { // } +/** Alias of (`'vevent' | string`). */ type tagname = 'vevent' | string +/** Alias of `string`. */ type uid = string /* TODO is this type correct? What really are valid values for any? Does that depend on ical_type? Why is the tail a list? What really is the type for the parameter map? */ +/* TODO link to RFC 7265 (jCal) */ +/** + * Alias for a record consisting of + * - the name of the type, as a string + * - all parameters of the object, as a `Record` + * - An `ical_type` value, noting the type of the final field(s) + * - and one or more values of the type specified by the third field. + */ type JCalProperty = [string, Record, ical_type, any] | [string, Record, ical_type, ...any[]] +/** + * A record consisting of a `tagname`, a list of + * `JCalProperties`, and a list of other `JCal` objects. +*/ type JCal = [tagname, JCalProperty[], JCal[]] +/** The xml namespace name for xcalendar */ const xcal = "urn:ietf:params:xml:ns:icalendar-2.0"; interface ChangeLogEntry { -- cgit v1.2.3 From e753d721519f72014241b3d2fc804a919f655769 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= Date: Thu, 7 Sep 2023 02:58:41 +0200 Subject: Document remaining javascript items. --- static/ts/types.ts | 42 ++++++++++++++++++++++++++++++++++-------- 1 file changed, 34 insertions(+), 8 deletions(-) (limited to 'static/ts/types.ts') diff --git a/static/ts/types.ts b/static/ts/types.ts index a0ab74a4..a01f6672 100644 --- a/static/ts/types.ts +++ b/static/ts/types.ts @@ -30,7 +30,7 @@ let all_types = [ ] -/* The union of all elements in `all_types`. */ +/** The union of all elements in `all_types`. */ type ical_type = 'text' | 'uri' @@ -104,6 +104,12 @@ let valid_fields: Map = new Map([ valid_fields.set('DAYLIGHT', valid_fields.get('STANDARD')!); +/** + All registered property types for VComponents. + + Note that only some of these are valid for each type of component (VCALENDAR, + VEVENT, ...), and that they all support both iana and `x-` extensions. + */ type known_ical_types = 'ACTION' | 'ATTACH' @@ -217,10 +223,7 @@ let valid_input_types: Map> = // type JCalLine { // } -/** Alias of (`'vevent' | string`). */ -type tagname = 'vevent' | string - -/** Alias of `string`. */ +/** The UID of a VEvent, to make declarations clearer. */ type uid = string /* TODO is this type correct? @@ -240,17 +243,40 @@ type JCalProperty | [string, Record, ical_type, ...any[]] /** - * A record consisting of a `tagname`, a list of - * `JCalProperties`, and a list of other `JCal` objects. + Base type for JCal documents. + + Each VComponent in a JCal document is of this form. + + - The first element is the components type + ('vevent', 'vcalendar', ...), in all lower case + - The second element is is all properties directly + on the component. + - The third element is a list of all children. */ -type JCal = [tagname, JCalProperty[], JCal[]] +type JCal = [string, JCalProperty[], JCal[]] /** The xml namespace name for xcalendar */ const xcal = "urn:ietf:params:xml:ns:icalendar-2.0"; +/** + An entry into a changelog. + + This is primarily used by VEvent, to track what has happened during a + session. + */ interface ChangeLogEntry { + /** + Type of change + + 'property' is used for changes to properties. + + 'calendar' is used when the containing calendar of a VEVENT is changed + */ type: 'calendar' | 'property', + /** The name of the filed changed */ name: string, + /** The previous value, `null` if just created */ from: string | null, + /** The new value, `null` if removed */ to: string | null, } -- cgit v1.2.3