Shareable-note-stickers NPM

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.)