0.0.43 • Published 1 year ago

shareable-note-stickers v0.0.43

Weekly downloads
-
License
MIT
Repository
github
Last release
1 year ago

shareable-note-stickers

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

NoteStickers Screenshot

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

0.0.43

1 year ago

0.0.42

1 year ago

0.0.40

1 year ago

0.0.39

1 year ago

0.0.38

1 year ago

0.0.37

1 year ago

0.0.35

1 year ago

0.0.34

1 year ago

0.0.33

1 year ago

0.0.32

1 year ago

0.0.31

1 year ago

0.0.30

1 year ago

0.0.29

1 year ago

0.0.28

1 year ago

0.0.27

1 year ago

0.0.26

1 year ago

0.0.25

1 year ago

0.0.24

1 year ago

0.0.23

1 year ago

0.0.22

1 year ago

0.0.21

1 year ago

0.0.20

1 year ago

0.0.19

1 year ago

0.0.18

1 year ago

0.0.17

1 year ago

0.0.16

1 year ago

0.0.15

1 year ago

0.0.14

1 year ago

0.0.13

1 year ago

0.0.12

1 year ago

0.0.11

1 year ago

0.0.10

1 year ago

0.0.9

1 year ago

0.0.8

1 year ago

0.0.7

1 year ago

0.0.6

1 year ago

0.0.5

1 year ago

0.0.4

1 year ago

0.0.3

1 year ago

0.0.2

1 year ago

0.0.1

1 year ago