scriptable-typings 0.1.0 → 0.2.0

package/README.md

@@ -1,3 +1,5 @@
 # scriptable-types
 
-Type definitions for [Scriptable](https://scriptable.app), using their [official documentation](https://docs.scriptable.app) as a reference
+Type definitions for [Scriptable](https://scriptable.app), all heavily based off of their [official documentation](https://docs.scriptable.app).
+
+We may use some of these types in our own projects. When we do confirm the typings for an item are correct, and we remember to update these typings, we will add a note to the item stating we have confirmed ourselves that the API works.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scriptable-typings",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "license": "MIT",
   "types": "src/types.d.ts",
   "files": [

package/src/types.d.ts

@@ -1,18 +1,21 @@
-declare class Alert {
-	title: string;
-	message: string;
-
-	constructor();
-
-	addAction(title: string);
-	addDestructiveAction(title: string);
-	addCancelAction(title: string);
-	addTextField(placeholder: string, text: string): TextField;
-	addSecureTextField(placeholder: string, text: string): TextField;
-	textFieldValue(index: number): string;
-	present(): Promise<number>;
-	presentAlert(): Promise<number>;
-	presentSheet(): Promise<number>;
+declare const config: Config;
+declare type Config = {
+	readonly runsInApp: boolean;
+	readonly runsInActionExtension: boolean;
+	readonly runsWithSiri: boolean;
+	readonly runsInWidget: boolean;
+	readonly runsInAccessoryWidget: boolean;
+	readonly runsInNotification: boolean;
+	readonly runsFromHomeScreen: boolean;
+	readonly widgetFamily:
+		| "small"
+		| "medium"
+		| "large"
+		| "extraLarge"
+		| "accessoryRectangular"
+		| "accessoryInline"
+		| "accessoryCircular"
+		| null;
 };
 
 declare const args: Args;
@@ -43,16 +46,132 @@ declare type Args = {
 	readonly notification: Notification;
 };
 
-declare class Calendar {
-	readonly identifier: string;
+/**
+ * Presents an alert
+ *
+ * Use this to configure an alert presented modally or as a sheet. After
+ * configuring the alert, call presentAlert() or presentSheet() to present the
+ * alert. The two presentation methods will return a value which carries the
+ * index of the action that was selected when fulfilled.
+ */
+declare class Alert {
+	/**
+	 * Title displayed in the alert (usually a short string)
+	 */
 	title: string;
-	readonly isSubscribed: boolean;
-	readonly allowsContentModifications: boolean;
-	color: Color;
 
-	supportsAvailability(availability: string): boolean;
-	save();
-	remove();
+	/**
+	 * Detailed message displayed in the alert
+	 */
+	message: string;
+
+	/**
+	 * Constructs a new alert
+	 */
+	constructor();
+
+	/**
+	 * Adds an action button to the alert
+	 *
+	 * Use the number value returned from presentAlert() or presentSheet() to
+	 * check which action was selected
+	 *
+	 * @param title Title of the action
+	 */
+	addAction(title: string): void;
+
+	/**
+	 * Adds a destructive action to the alert
+	 *
+	 * Destructive action titles have a red text color, signaling that the
+	 * action may modify or delete data.
+	 *
+	 * @param title Title of the action
+	 */
+	addDestructiveAction(title: string): void;
+
+	/**
+	 * Adds a cancel action to the alert
+	 *
+	 * When a cancel action is selected, the number provided by presentAlert()
+	 * or presentSheet() will be `-1`. Please note that when running on iPad
+	 * and presenting using presentSheet(), the action will not be shown in the
+	 * list of actions. The operation is cancelled by tapping outside the sheet.
+	 *
+	 * An alert can only contain a single cancel action. Attempting to add more
+	 * cancel actions will remove any previously added cancel actions.
+	 *
+	 * @param title Title of the action
+	 */
+	addCancelAction(title: string): void;
+
+	/**
+	 * Adds a text field prompting for user input
+	 *
+	 * Retrieve the value for the text field using textFieldValue() and supply
+	 * the index of the text field. Indices for text fields are assigned in the
+	 * same order as they are added to the alert starting at 0.
+	 *
+	 * Text fields are not supported when using the sheet presentation.
+	 *
+	 * @param placeholder Optional placeholder displayed when the text field is empty
+	 * @param text Optional default value for the text field
+	 * @returns Text field added to the alert
+	 */
+	// todo those two params are documented as optional? what does this mean typewise? is null/undefined fine?
+	addTextField(placeholder: string, text: string): TextField;
+
+	/**
+	 * Adds a secure text field prompting for user input
+	 *
+	 * Values entered into a secure text field will be hidden behind dots.
+	 * Retrieve the value for the text field using textFieldValue() and supply
+	 * the index of the text field. Indices for text fields are assigned in the
+	 * same order as they are added to the alert starting at 0.
+	 *
+	 * @param placeholder Optional placeholder displayed when the text field is empty
+	 * @param text Optional default value for the text field
+	 * @returns Text field added to the alert
+	 */
+	// todo same as above, types of params are optional?
+	addSecureTextField(placeholder: string, text: string): TextField;
+
+	/**
+	 * Retrieves value of a text field by index
+	 *
+	 * Indices for text fields are assigned in the same order as they are added
+	 * to the alert starting at 0.
+	 *
+	 * @param index Index of text field to retrieve the value for
+	 * @returns Value of text field at the specified index
+	 */
+	textFieldValue(index: number): string;
+
+	/**
+	 * Present the alert modally
+	 *
+	 * This is a shorthand for presentAlert().
+	 *
+	 * @returns Promise resolving to the chosen action index
+	 */
+	present(): Promise<number>;
+
+	/**
+	 * Present the alert modally
+	 *
+	 * @returns Promise resolving to the chosen action index
+	 */
+	presentAlert(): Promise<number>;
+
+	/**
+	 * Present the alert as a sheet
+	 *
+	 * @returns Promise resolving to the chosen action index
+	 */
+	presentSheet(): Promise<number>;
+}
+
+declare class Calendar {
 	static forReminders(): Promise<Array<Calendar>>;
 	static forEvents(): Promise<Array<Calendar>>;
 	static forRemindersByTitle(title: string): Promise<Calendar>;
@@ -64,62 +183,412 @@ declare class Calendar {
 	// todo i'm guessing these, need to test
 	static presentPicker(allowMultiple: true): Promise<Array<Calendar>>;
 	static presentPicker(allowMultiple: false): Promise<[Calendar?]>;
-};
+
+	readonly identifier: string;
+	title: string;
+	readonly isSubscribed: boolean;
+	readonly allowsContentModifications: boolean;
+	color: Color;
+
+	// todo ???
+	private constructor();
+
+	supportsAvailability(availability: string): boolean;
+	save(): void;
+	remove(): void;
+}
 
 // todo CalendarEvent
+
 // todo CallbackURL
-// todo Color
-// todo config
+
+declare class Color {
+	static black(): Color;
+	static darkGray(): Color;
+	static lightGray(): Color;
+	static white(): Color;
+	static gray(): Color;
+	static red(): Color;
+	static green(): Color;
+	static blue(): Color;
+	static cyan(): Color;
+	static yellow(): Color;
+	static magenta(): Color;
+	static orange(): Color;
+	static purple(): Color;
+	static brown(): Color;
+	static clear(): Color;
+	static dynamic(lightColor: Color, darkColor: Color): Color;
+
+	readonly hex: string;
+	readonly red: number;
+	readonly green: number;
+	readonly blue: number;
+	readonly alpha: number;
+
+	constructor(hex: string, alpha: number);
+}
+
 // todo console
+
 // todo Contact
+
 // todo ContactsContainer
+
 // todo ContactsGroup
-// todo Data
+
+declare class Data {
+	static fromString(string: string): Data | null;
+	static fromFile(filepath: string): Data;
+	static fromBase64String(base64String: string): Data | null;
+	static fromJPEG(image: Image): Data;
+	static fromPNG(image: Image): Data;
+	static fromBytes(bytes: Array<number>): Data;
+
+	// todo ???
+	private constructor();
+
+	toRawString(): string;
+	toBase64String(): string;
+	getBytes(): Array<number>;
+}
+
 // todo DateFormatter
+
 // todo DatePicker
+
 // todo Device
+
 // todo Dictation
+
 // todo DocumentPicker
+
 // todo DrawContext
+
 // todo FileManager
-// todo Font
-// todo Image
+
+declare class Font {
+	static largeTitle(): Font;
+	static title1(): Font;
+	static title2(): Font;
+	static title3(): Font;
+	static headline(): Font;
+	static subheadline(): Font;
+	static body(): Font;
+	static callout(): Font;
+	static footnote(): Font;
+	static caption1(): Font;
+	static caption2(): Font;
+	static systemFont(size: number): Font;
+	static ultraLightSystemFont(size: number): Font;
+	static thinSystemFont(size: number): Font;
+	static lightSystemFont(size: number): Font;
+	static regularSystemFont(size: number): Font;
+	static mediumSystemFont(size: number): Font;
+	static semiboldSystemFont(size: number): Font;
+	static boldSystemFont(size: number): Font;
+	static heavySystemFont(size: number): Font;
+	static blackSystemFont(size: number): Font;
+	static italicSystemFont(size: number): Font;
+	static ultraLightMonospacedSystemFont(size: number): Font;
+	static thinMonospacedSystemFont(size: number): Font;
+	static lightMonospacedSystemFont(size: number): Font;
+	static regularMonospacedSystemFont(size: number): Font;
+	static mediumMonospacedSystemFont(size: number): Font;
+	static semiboldMonospacedSystemFont(size: number): Font;
+	static boldMonospacedSystemFont(size: number): Font;
+	static heavyMonospacedSystemFont(size: number): Font;
+	static blackMonospacedSystemFont(size: number): Font;
+	static ultraLightRoundedSystemFont(size: number): Font;
+	static thinRoundedSystemFont(size: number): Font;
+	static lightRoundedSystemFont(size: number): Font;
+	static regularRoundedSystemFont(size: number): Font;
+	static mediumRoundedSystemFont(size: number): Font;
+	static semiboldRoundedSystemFont(size: number): Font;
+	static boldRoundedSystemFont(size: number): Font;
+	static heavyRoundedSystemFont(size: number): Font;
+	static blackRoundedSystemFont(size: number): Font;
+
+	constructor(name: string, size: number);
+}
+
+declare class Image {
+	static fromFile(filePath: string): Image | null;
+	static fromData(data: Data): Image | null;
+
+	// todo ???
+	private constructor();
+
+	readonly size: Size;
+}
+
 // todo importModule
+
 // todo Keychain
-// todo LinearGradient
+
+declare class LinearGradient {
+	colors: Array<Color>;
+	locations: Array<number>;
+	startPoint: Point;
+	endPoint: Point;
+
+	constructor();
+}
+
 // todo ListWidget
+
 // todo Location
+
 // todo Mail
+
 // todo Message
+
 // todo module
-// todo Notification
+
+declare class Notification {
+	/**
+	 * @deprecated
+	 */
+	static current(): Notification;
+	static allPending(): Promise<Array<Notification>>;
+	static allDelivered(): Promise<Array<Notification>>;
+	static removeAllPending(): Promise<Array<Notification>>;
+	static removeAllDelivered(): Promise<Array<Notification>>;
+	static removePending(identifiers: Array<string>): Promise<void>;
+	static removeDelivered(identifiers: Array<string>): Promise<void>;
+	static resetCurrent(): void;
+
+	identifier: string;
+	title: string;
+	subtitle: string;
+	body: string;
+	preferredContentHeight: number;
+	badge: number;
+	threadIdentifier: string;
+	userInfo: { [k: string]: unknown };
+	sound:
+		| "default"
+		| "accept"
+		| "alert"
+		| "complete"
+		| "event"
+		| "failure"
+		| "piano_error"
+		| "piano_success"
+		| "popup"
+		| null;
+	openURL: string;
+	readonly deliveryDate: Date | null;
+	nextTriggerDate: Date;
+	scriptName: string;
+	actions: { [k: string]: string };
+
+	constructor();
+
+	schedule(): Promise<void>;
+	remove(): Promise<void>;
+	setTriggerDate(date: Date): void;
+	setDailyTrigger(hour: number, minute: number, repeats: boolean): void;
+	setWeeklyTrigger(weekday: number, hour: number, minute: number, repeats: boolean): void;
+	addAction(title: string, url: string, destructive: boolean): void;
+}
+
 // todo Pasteboard
+
 // todo Path
+
 // todo Photos
-// todo Point
+
+declare class Point {
+	x: number;
+	y: number;
+
+	constructor(x: number, y: number);
+}
+
 // todo QuickLook
+
 // todo Rect
+
 // todo RecurrenceRule
+
 // todo RelativeDateTimeFormatter
+
 // todo Reminder
+
 // todo Request
+
 // todo Safari
+
 // todo Script
+
 // todo SFSymbol
+
 // todo ShareSheet
-// todo Size
+
+declare class Size {
+	width: number;
+	height: number;
+
+	constructor(width: number, height: number);
+}
+
 // todo Speech
-// todo TextField
+
+declare class TextField {
+	text: string;
+	placeholder: string;
+	isSecure: boolean;
+	textColor: Color;
+	font: Font;
+
+	private constructor();
+
+	setDefaultKeyboard(): void;
+	setNumberPadKeyboard(): void;
+	setDecimalPadKeyboard(): void;
+	setNumbersAndPunctuationKeyboard(): void;
+	setPhonePadKeyboard(): void;
+	setWebSearchKeyboard(): void;
+	setEmailAddressKeyboard(): void;
+	setURLKeyboard(): void;
+	setTwitterKeyboard(): void;
+	leftAlignText(): void;
+	centerAlignText(): void;
+	rightAlignText(): void;
+
+}
+
 // todo Timer
+
 // todo UITable
+
 // todo UITableCell
+
 // todo UITableRow
+
 // todo URLScheme
+
 // todo UUID
+
 // todo WebView
+
 // todo WidgetDate
-// todo WidgetImage
-// todo WidgetSpacer
-// todo WidgetStack
-// todo WidgetText
-// todo XMLParser
+declare class WidgetDate {
+	date: Date;
+	textColor: Color;
+	font: Font;
+	textOpacity: number;
+	lineLimit: number;
+	minimumScaleFactor: number;
+	shadowColor: Color;
+	shadowRadius: number;
+	shadowOffset: Point;
+	url: string;
+
+	private constructor();
+
+	leftAlignText(): void;
+	centerAlignText(): void;
+	rightAlignText(): void;
+	applyTimeStyle(): void;
+	applyDateStyle(): void;
+	applyRelativeStyle(): void;
+	applyOffsetStyle(): void;
+	applyTimerStyle(): void;
+}
+
+declare class WidgetImage {
+	image: Image;
+	resizable: boolean;
+	imageSize: Size;
+	imageOpacity: number;
+	cornerRadius: number;
+	borderWidth: number;
+	borderColor: Color;
+	containerRelativeShape: boolean;
+	tintColor: Color;
+	url: string;
+
+	private constructor();
+
+	leftAlignImage(): void;
+	centerAlignImage(): void;
+	rightAlignImage(): void;
+	applyFittingContentMode(): void;
+	applyFillingContentMode(): void;
+}
+
+declare class WidgetSpacer {
+	length: number | null;
+
+	// todo ???
+	private constructor();
+}
+
+declare class WidgetStack {
+	backgroundColor: Color;
+	backgroundImage: Image;
+	backgroundGradient: LinearGradient;
+	spacing: number;
+	size: Size;
+	cornerRadius: number;
+	borderWidth: number;
+	borderColor: Color;
+	url: string;
+
+	// todo ???
+	private constructor();
+
+	addText(text: string): WidgetText;
+	addDate(date: Date): WidgetDate;
+	addImage(image: Image): WidgetImage;
+	addSpacer(length: number): WidgetSpacer;
+	addStack(): WidgetStack;
+	setPadding(top: number, leading: number, bottom: number, trailing: number): void;
+	useDefaultPadding(): void;
+	topAlignContent(): void;
+	centerAlignContent(): void;
+	bottomAlignContent(): void;
+	layoutHorizontally(): void;
+	layoutVertically(): void;
+}
+
+declare class WidgetText {
+	text: string;
+	textColor: Color;
+	font: Font;
+	textOpacity: number;
+	lineLimit: number;
+	minimumScaleFactor: number;
+	shadowColor: Color;
+	shadowRadius: number;
+	shadowOffset: Point;
+	url: string;
+
+	// todo ???
+	private constructor();
+
+	leftAlignText(): void;
+	centerAlignText(): void;
+	rightAlignText(): void;
+}
+
+// todo I set the event functions as optional because I'm guessing you can't
+// read out a function from them before you set one, should verify this is true
+declare class XMLParser {
+	didStartDocument?: () => void;
+	didEndDocument?: () => void;
+	didStartElement?: (
+		elementName: string,
+		attributes: { [k: string]: string }
+	) => void;
+	didEndElement?: () => void;
+	foundCharacters?: () => void;
+	parseErrorOccured?: () => void;
+	string: string;
+
+	constructor(string: string);
+
+	parse(): boolean;
+}