shareable-note-stickers

basic data model for a shareable application with scriptable "sticky notes"

Overview

This module implements the underlying data model for a shareable hierarchical collection of "boards" containing scriptable widgets (called "stickers").

It will often be used in combination with

• sns-boardview - a preact component that displays one of these boards of stickers and provides all methods to visually select and edit them, and
• a "sharing adapter" such as the sns-collabs-adapter that actually provides the sharing capability.

To get a real application, you'll have to combine these modules and add a proper user interface - as done by NoteStickers.

Because of this modularity, it is not too difficult to use a different sharing framework (such as Y.js or automerge), modify the user interface according to your personal needs or even develop a headless tool that analyzes and/or changes the shared data without user intervention.

(work in progress, see NoteStickers for a first usage example)

Usage

"shareable-note-stickers" is intended for being used as a module within a "host application". In order to use it, simply import the necessary types, constants, functions and classes:

  import {
    throwError, throwReadOnlyError,
    ValueIsBoard, ValueIsSticker,
    ValueIsName, ValueIsIdentifier, ValueIsGeometry, ValueIsError,
    allowBoard,
    SNS_Id, SNS_Name, SNS_Identifier,
    SNS_Ordinal, SNS_Text, SNS_Textline, SNS_Color, SNS_URL,
    SNS_Geometry, SNS_FontStyle, SNS_Error,
    SNS_Visual, SNS_Folder, SNS_Project, SNS_Board, SNS_Sticker,
    newId, removeIdsFrom, SNS_Change,
    TemplateOfBehavior,
    SNS_BehaviorEntryGroup, SNS_BehaviorEntry,
    groupedBehaviorEntryList,
  } from 'https://rozek.github.io/shareable-note-stickers/dist/shareable-note-stickers.modern.js'

(Note: the above import statement is just an example - your imports may differ)

To simplify scripting, most of the exported functions are also available as part of the global variable SNS

  window.SNS = {
    SNS_FontStyles, SNS_ErrorTypes,
    SNS_matchableProperties, SNS_MatchModes,
    throwError, throwReadOnlyError,
    ValueIsVisual, allowVisual, allowedVisual, expectVisual, expectedVisual,
    ValueIsFolder, allowFolder, allowedFolder, expectFolder, expectedFolder,
    ValueIsProject, allowProject, allowedProject, expectProject, expectedProject,
    ValueIsBoard, allowBoard, allowedBoard, expectBoard, expectedBoard,
    ValueIsSticker, allowSticker, allowedSticker, expectSticker, expectedSticker,
    ValueIsId, allowId, allowedId, expectId, expectedId,
    ValueIsIdentifier, allowIdentifier, allowedIdentifier, expectIdentifier, expectedIdentifier,
    ValueIsName, allowName, allowedName, expectName, expectedName,
    ValueIsLocation, allowLocation, allowedLocation, expectLocation, expectedLocation,
    ValueIsDimension, allowDimension, allowedDimension, expectDimension, expectedDimension,
    ValueIsPosition, allowPosition, allowedPosition, expectPosition, expectedPosition,
    ValueIsSize, allowSize, allowedSize, expectSize, expectedSize,
    ValueIsGeometry, allowGeometry, allowedGeometry, expectGeometry, expectedGeometry,
    ValueIsError, allowError, allowedError, expectError, expectedError,
    ValueIsSerializableObject, allowSerializableObject, allowedSerializableObject, expectSerializableObject, expectedSerializableObject,
    ValueIsSerializableValue, allowSerializableValue, allowedSerializableValue, expectSerializableValue, expectedSerializableValue,
    acceptableBoolean, acceptableOptionalBoolean,
    acceptableNumber, acceptableOptionalNumber,
    acceptableNumberInRange, acceptableOptionalNumberInRange,
    acceptableInteger, acceptableOptionalInteger,
    acceptableIntegerInRange, acceptableOptionalIntegerInRange,
    acceptableOrdinal, acceptableOptionalOrdinal,
    acceptableString, acceptableOptionalString,
    acceptableNonEmptyString, acceptableOptionalNonEmptyString,
    acceptableStringMatching, acceptableOptionalStringMatching,
    acceptableText, acceptableOptionalText,
    acceptableTextline, acceptableOptionalTextline,
    acceptableFunction, acceptableOptionalFunction,
    acceptableList, acceptableOptionalList,
    acceptableListSatisfying, acceptableOptionalListSatisfying,
    acceptableColor, acceptableOptionalColor,
    acceptableEMailAddress, acceptablePhoneNumber, acceptableURL,
    newId, removeIdsFrom,
    CSSStyleOfVisual,
    TemplateOfBehavior,
  }

Exports

"shareable-note-stickers" exports a few types and classes, and a bunch of helper functions.

Types and Constants

Type exports are for TypeScript users only - all others may simply skip this section.

• type SNS_Id = string
• type SNS_Identifier = string
• type SNS_Name = string
• type SNS_Ordinal = string
• type SNS_Cardinal = string
• type SNS_Text = string
• type SNS_Textline = string
• type SNS_URL = string
• type SNS_Color = string  
• type SNS_Location = number
• type SNS_Dimension = number
• type SNS_Position = { x:SNS_Location,y:SNS_Location }
• type SNS_Size = { Width:SNS_Dimension,Height:SNS_Dimension }
• type SNS_Geometry = { x:SNS_Location,y:SNS_Location, Width:SNS_Dimension,Height:SNS_Dimension }  
• const SNS_FontStyles = ['normal','italic']
• type SNS_FontStyle = typeof SNS_FontStyles[number]

Rendering

• type SNS_onRenderingCallback = ( Project:SNS_Project, Board?:SNS_Board, Sticker?:SNS_Sticker) => void

Search Support

• const SNS_MatchModes = ['equality','containment','match']
• type SNS_MatchMode = typeof SNS_MatchModes[number]  
• const SNS_matchableProperties = ['Name','Value','Script']
• type SNS_matchableProperty = typeof SNS_matchableProperties[number]
• type SNS_matchablePropertySet = { [Key:string]:boolean }  
• type SNS_ErrorRelevance = null|boolean  
• type SNS_VisualMatch = { Visual:SNS_Visual, Property?:SNS_matchableProperty, StartIndex?:SNS_Ordinal, EndIndex?:SNS_Ordinal}

Dialogs

• type SNS_Dialog = { Id:SNS_Id, Name:SNS_Name, Title:SNS_Textline, isResizable:boolean, x:SNS_Location, y:SNS_Location, Width:SNS_Dimension, Height:SNS_Dimension, minWidth:number, maxWidth?:number, minHeight:number, maxHeight?:number, Visibility:boolean, Renderer:Function, onClose?:Function}

Change Reporting

• const SNS_Changes = [ 'createBoard', 'configureFolder', 'attachBoard', 'detachBoard', 'destroyBoard', 'createSticker', 'configureSticker', 'attachSticker', 'detachSticker', 'destroySticker',]
• type SNS_Change = typeof SNS_Changes[number]  
• type SNS_onChangeCallback = ( Project:SNS_Project, Change:SNS_Change, Id:SNS_Id, ...ArgList:any[]) => void

Error Reporting

• const SNS_ErrorTypes = [ 'missing Behaviour', 'Behaviour Execution Failure', 'Script Compilation Failure','Script Execution Failure', 'Rendering Failure', 'Event Handling Failure', '"onMount" Callback Failure','"onUnmount" Callback Failure']
• type SNS_ErrorType = typeof SNS_ErrorTypes[number]  
• type SNS_Error = { Type:SNS_ErrorType, Message:SNS_Text, Cause:any}  
• type SNS_onErrorCallback = ( Project:SNS_Project, Visual:SNS_Visual, Error:SNS_Error) => void

UI Support

• type SNS_groupedBehaviorEntryList = SNS_BehaviorEntryGroup[]
• type SNS_BehaviorEntryGroup = { GroupLabel:SNS_Textline, BehaviorEntryList:SNS_BehaviorEntry[] }
• type SNS_BehaviorEntry = { Label:SNS_Textline, Name:SNS_Identifier, disabled:boolean }

(t.b.w.)

SNS_Visual

• Id
• Name  
• Project
• Folder
• isAttached
• Application  
• BackgroundColor
• BackgroundTexture
• FontFamily
• FontSize
• FontWeight
• FontStyle
• LineHeight
• ForegroundColor
• Color  
• Value
• editableValue  
• observed
• unobserved
• memoized  
• Script
• activeScript
• pendingScript
• activateScript
• ScriptError  
• CSSStyle
• Renderer
• onRender
• Rendering
• rerender  
• View
• isMounted
• onMount
• onUnmount  
• Error
• hasError  
• ownMatchesFor
• allMatchesFor

(t.b.w.)

SNS_Folder (extends SNS_Visual)

• Path
• BoardAtPath
• IndexPath  
• SnapToGrid
• GridWidth
• GridHeight  
• Index
• maybeShiftedUp
• mayBeShiftedDown
• mayBeShiftedIn
• mayBeShiftedOut  
• containsFolder  
• BoardList
• BoardCount
• Board
• existingBoard
• BoardNamed
• BoardAt
• hasBoard  
• newBoardAt
• BoardDeserializedAt
• DuplicateOfBoardAt  
• mayShiftBoardUp
• mayShiftBoardDown
• shiftBoardToTop
• shiftBoardUp
• shiftBoardDown
• shiftBoardToBottom
• shiftBoardTo
• shiftBoardsByIndex  
• mayShiftBoardIn
• mayShiftBoardOut
• shiftBoardIn
• shiftBoardOut  
• mayMoveBoardTo
• moveBoardTo  
• destroyBoard
• clear

(t.b.w.)

SNS_Project (extends SNS_Folder)

• BoardAtIndexPath  
• FolderWithId
• BoardWithId
• StickerWithId  
• recursivelyActivateAllScripts  
• onChange  
• onRendering
• rerender  
• onError  
• Application  
• Serialization
• deserializedFrom

(t.b.w.)

SNS_Board (extends SNS_Folder)

• StickerList
• StickerCount
• IndexOfSticker
• Sticker
• existingSticker
• StickerNamed
• StickerAt
• hasSticker  
• newStickerAt
• StickerDeserializedAt
• DuplicateofStickerAt  
• mayShiftStickerUp
• mayShiftStickerDown
• shiftStickerToTop
• shiftStickerUp
• shiftStickerDown
• shiftStickerToBottom
• shiftStickerTo
• shiftStickersByIndex  
• destroySticker
• clear  
• onClick
• onDrop  
• DialogList
• IndexOfDialog
• openDialog
• DialogIsOpen
• openTextViewDialog
• openHTMLViewDialog
• openImageViewDialog
• openSVGViewDialog
• openWebViewDialog
• positionDialogAt
• sizeDialogTo
• DialogIsFrontmost
• bringDialogToFront
• closeDialog
• closeAllDialogs  
• Serialization

(t.b.w.)

SNS_Sticker (extends SNS_Visual)

• Board  
• Index
• mayBeShiftedUp
• mayBeShiftedDown  
• minWidth
• maxWidth
• minHeight
• maxHeight
• x
• y
• Width
• Height
• Position
• Size
• Geometry  
• Lock
• isLocked
• lock
• unlock  
• Selectability
• isSelectable  
• Visibility
• show
• hide
• isVisible  
• Enabling
• enable
• disable
• isEnabled  
• onClick
• onDrop  
• Rendering
• rerender  
• Serialization

(t.b.w.)

SNS_Adapter

• ConnectionState
• isConnected  
• connect
• disconnect

(t.b.w.)

Classification and Validation Functions

• ValueIsVisual, allow/expect[ed]Visual
• ValueIsFolder, allow/expect[ed]Folder  
• ValueIsProjec, allow/expect[ed]Project
• ValueIsBoard, allow/expect[ed]Board
• ValueIsSticker, allow/expect[ed]Sticker  
• ValueIsId, allow/expect[ed]Id
• ValueIsIdentifie, allow/expect[ed]Identifier
• ValueIsName, allow/expect[ed]Name  
• ValueIsLocation, allow/expect[ed]Location
• ValueIsDimension, allow/expect[ed]Dimension
• ValueIsPosition, allow/expect[ed]Position
• ValueIsSize, allow/expect[ed]Size
• ValueIsGeometry, allow/expect[ed]Geometry  
• ValueIsError, allow/expect[ed]Error  
• ValueIsSerializableObject, allow/expect[ed]SerializableObject
• ValueIsSerializableValue, allow/expect[ed]SerializableValue

(t.b.w.)

Acceptables

• acceptable[Optional]Boolean
• acceptable[Optional]Number
• acceptable[Optional]NumberInRange
• acceptable[Optional]Integer
• acceptable[Optional]IntegerInRange
• acceptable[Optional]Ordinal
• acceptable[Optional]String
• acceptable[Optional]NonEmptyString
• acceptable[Optional]StringMatching
• acceptable[Optional]Text
• acceptable[Optional]Textline
• acceptable[Optional]Function
• acceptable[Optional]List
• acceptable[Optional]ListSatisfying
• acceptable[Optional]Color
• acceptable[Optional]EMailAddress
• acceptable[Optional]PhoneNumber
• acceptable[Optional]URL

(t.b.w.)

Adapter Support

• attachBoard
• attachSticker
• detachBoard
• detachSticker  
• createBoard
• createSticker
• destroyBoard
• destroySticker  
• configureFolder
• configureSticker  
• sanitizeBoardList
• sanitizeStickerList

(t.b.w.)

UI Support

• groupedBehaviorEntryList

(t.b.w.)

Others

• throwError
• throwReadOnlyError  
• removeIdsFrom  
• TemplateOfBehavior  
• CSSStyleOfVisual

(t.b.w.)

File Format

The following JSON schema describes the file format used for exported NoteSticker projects:

(t.b.w.)

License

MIT License