Shellfish

Index

Shellfish Declarative Toolkit

Introduction

In short, Shellfish is a declarative toolkit for JavaScript environments and targets full-stack development. This means, it covers both, the client UI and the server side.

Its runtime has no additional dependencies and works on any compatible JavaScript runtime environment, including:

  • Modern web browsers
  • Node.js
  • Runtime environments like Electron or Capacitor

Shellfish also features Shui, a modeling language taking full advantage of Shellfish's declarative nature.

This is what the obligatory "Hello, world!" example could look like in Shui code:

require "shellfish/ui";

Document {

    title: "Hello, world of declarative programming!"

    Label {
        text: parent.title
    }

}

Shui code is translated to JavaScript code before execution. This can either happen on the fly as the code gets loaded, or on the server-side on demand, or even by shipping only pre-translated code. It's your choice.

Learn to Use Shellfish (work in progress)

The Basics

Introduction to Shui

Shui is the declarative description language used by Shellfish.

Layout Concepts for UI

Layouting UI elements on screen is intuitive, yet powerful.

Generic Topics

UI Topics

Server Programming

Shellfish provides elements for building servers with Shui code.

News

April 2024

  • The element core.Repeater is now capable of creating and destroying its child items selectively with the dynamicItems property.

March 2024

January 2024

  • Improved UI performance.
  • The new element ui.NotificationArea lets you display notification popups in your application.
  • API Break: The deprecated mouse events of html.MouseBox have been removed.

December 2023

November 2023

  • require.js is now the same as require2.js and require2.js is going to be removed eventually. The previous version of require.js is currently available as requireLegacy.js.
  • The element core.TreeModelAdapter has a new property dynamicContentProvider for populating the model with content dynamically when uncollapsing a node.
  • The new element core.RegistryFile provides a file-backed easy-to-use hierarchical registry database for storing configurations.
  • The new element core.RegistryOverlay provides an overlay over a registry for temporary changes that can then be either applied or cancelled.
  • It is now possible in Shui code to assign Promise objects to properties, and the property will be set when the Promise resolves.

October 2023

  • The element ui.Button is now stylable with templates.
  • The new function core.formatBytes can be used to format a bytes number to a human-readable string.
  • The element ui.FSItem now supports the value compact for its displayMode property for a more compact item layout suitable for small screens.
  • API Break: The deprecated element core.Wasm has been removed. WebAssembly modules can be imported directly.

August 2023

  • The modelData property is now only defined on elements where needed. This makes it possible to access the modelData property of a delegate from further down the hierarchy.
  • The element core.RpcProxy now has a status property for monitoring the connection status.
  • The new elements core.TreeModelAdapter and ui.TreeBranch help to implement collapsible tree views based on a list model.

July 2023

  • The new function core.generateUid generates a UID that is unique within the Shellfish environment.
  • The element ui.ScrollIndicator has a new property reverse for reversing the scrolling direction.
  • The new element core.InertialEngine provides a simple physics engine for inertial motion with friction.
  • The new element ui.FlickGesture adds flick gestures for scrolling to a html.MouseBox.
  • Ancestor references such as thisDocument or thisMenu are now implemented via the resolver function in Shui code and no longer take up a property. Thus, the this... references are now available for all elements in Shui code.
  • The new keyword unresolved can be used before JavaScript blocks in Shui to process the block as unresolved, i.e. without the Shui resolver overhead.
  • Elements derived from html.Item have new shortcut properties fill and margins for setting fillWidth and fillHeight, respectively marginTop, marginBottom, marginLeft, marginRight to the same value.
  • API-Break: The file data returned by core.Filesystem#read and passed to core.Filesystem#write has been unified to the new type core.Filesystem.FileData.
  • The RPC protocol between core.RpcProxy and server.RpcSession now supports transfering Uint8Array parameters in binary form.
  • The new element core.ScaleModel provides a list model for generating scale displays.

June 2023

May 2023

April 2023

  • The method core.Filesystem#write now takes an optional progress callback function for monitoring the upload progress where supported.
  • The new element ui.MenuExpander provides an expandable menu item with sub items.

March 2023

  • Performance optimizations.
  • Reference cycles are detected automatically at run-time and are logged to the debug console. Make sure to keep an eye on your cycles and resolve them properly in order to avoid memory leaks.

February 2023

  • The element html.Video can now load subtitles in VTT format with the properties subtitles and cues.
  • The new UI element ui.ListHeader provides a simple list header with multiple columns for placing directly above a html.ListView.
  • API-Break: The properties withDirectories, withFiles, and withHidden have been removed from the element core.FSModel. Use the filter property instead for setting a filtering function. Simple filtering functions can be created via core.FSModel#makeFilter.

January 2023

December 2022

  • Reworked the inner HTML and CSS update mechanisms for better performance when rendering content in a browser.

November 2022

  • The nullish-coalescing operator (??) can now be used in Shui code.
  • The optional-chaining operator (?.) can now be used in Shui code.
  • The ui.Button element has the new property repeatAcceleration for repeated triggering while holding down.
  • The element ui.Slider is now stylable with templates.
  • The element ui.SpinBox is now stylable with templates.
  • The element ui.SplitBox is now stylable with templates.
  • The element ui.Switch is now stylable with templates.
  • The new property order of html.Item allows you to change the layout order of elements dynamically.

October 2022

  • The element html.ListView has a new property overflowBehavior for disabling or enabling scrolling.
  • The element html.ListView has a new property snapMode for snapping to items after scrolling.
  • The new property scrolling of html.Item tells if an item is currently scrolling its content.

September 2022

  • The new element ui.MultiSelectionBox provides a selection box for multi-selections.
  • The new method core.Object#waitQueued allows for asynchronous actions to wait in a named queue. The method core.Object#clearQueue clears a named queue, cancelling all waiting actions.
  • It is now possible to build Shellfish packages with ES2015 syntax for running in legacy environments by using the Babel compiler while bundling. Pass the --legacy option to make-bundle.js to enable.
  • API Break: The element ui.FSItem has no property filesystem anymore. The path given to thumbnail is an URL now, e.g. a Blob URL.

August 2022

  • Some of the most common basic element types are preproduced and held in stock by shellfish/declarative for better element creation performance with Shui.
  • Elements derived from html.Item have the new bounding box properties bboxX, bboxY, bboxWidth, and bboxHeight. Using these usually gives a better performance than referencing particular members of the bbox property.
  • The element server.HTTPServer has the new property enabled for turning the server on or off.
  • The element core.FileStorage has the new read-only property ready to get notified when the file storage is loaded and ready.

July 2022

  • The new element shf3d.Surface provides a flat rectangular 2D surface for use in 3D scenes.

May 2022

  • API Break: The module shellfish/high is now named shellfish/declarative. Since this module is usually not imported directly by application code, applications should not be affected by this API break.
  • WebAssembly is now directly supported by the module loader, so WASM modules may be loaded like any other Shellfish module or JavaScript file. The element core.Wasm is thus deprecated and should not be used in new code. It will be removed eventually.
  • The new method core.Object#import imports JavaScript, CSS, or WASM modules dynamically.

April 2022

  • The new method core.Object#log provides a simple means for controlling application logging.
  • The new method server.HTTPResponse#enableCrossOriginIsolation provides a comfortable way to set the HTTP headers for cross-origin-isolation on a HTTP response.
  • The examples gallery is now included in the main distribution.
  • The module shellfish/3d is now included in the main distribution.

February 2022

  • The function keyword may now be used in JavaScript sections of Shui files.
  • Shellfish is expanding its reach to the server-side to allow full-stack implementations with declarative Shui code and the new shellfish-server API.
  • API Break: The module shellfish/mid is now named shellfish/html and is no longer imported by default in Shui documents. Shui modules with UI code should import shellfish/ui (which includes shellfish/html).
  • The method ui.Menu#popup accepts null as the parent parameter to open the menu near the mouse pointer.
  • The element html.Document has the new non-notifyable properties pointerX and pointerY for accessing the document-global pointer coordinates.

January 2022

  • The new method html.ListModel#insertOrdered inserts items into a list model according to a custom comparator function.
  • The new method html.Object#wait lets you delay actions asynchronously.
  • The elements html.TextInput and html.TextArea have a new method selectRange for selecting a range of text programmatically.
  • The PointerEvent of html.MouseBox has a new boolean property directTarget, which tells if the MouseBox was targeted directly, i.e. the event did not come through another MouseBox.

November 2021

  • Some rendering issues in the html.ListView element have been fixed.
  • The superfluous dataChange event has been removed from html.Object. In case of delegate items, the modelDataChanged event does the same.
  • The new elements ui.Window and ui.WindowTitle provide a way to put draggable and resizable floating windows into a parent box.
  • The html.Repeater element now arranges spawned items in the order given by its model when modifying the model.
  • The new element ui.OverflowScroller provides a way for the user to scroll overflowing toolbars and other boxes.
  • The filesystem implementations html.DavFS and html.OfflineFS have a move operation now, and file info objects have ctime and mtime fields for the creation time and modification time, respectively.
  • The element html.MouseBox can now detect clicks even if a drag handler is connected. Compatibility issues with the Sailfish Browser have been fixed.
  • The element ui.SplitBox has the new properties orientation for changing the layout orientation, and flip for flipping both containers. The new property splitRatio lets you change the split ratio programmatically.

October 2021

  • The element html.Repeater has a new property count that tells the number of spawned items.
  • The element html.TextArea has a new method shiftRows for shifting a block of rows.
  • The element html.TextArea has a new method rowAt for retrieving the row number at a given text position.
  • The element ui.TextArea has new containers backgroundContainer, bottomMarginContainer, topMarginContainer, leftMarginContainer, and rightMarginContainer for decorations such as line numbers, syntax highlighting, etc.
  • The JavaScript regular expressions syntax (e.g. /abc.*[0-9]/i) may now be used in Shui files.
  • There are new elements html.SyntaxHighlighter and html.SyntaxToken for defining syntax highlighting rules for text.
  • The element html.Label has a new property filter for implementing advanced text processing, e.g. syntax highlighting.
  • The element html.TextArea has a new property caretColor for changing the caret color.
  • The new elements html.LocalStorage and html.FileStorage persist any of their custom properties to the HTML5 local storage or a file on a html.Filesystem automatically.
  • The new element html.History allows to control the browser history.
  • The new function low.later returns a Promise object that resolves when idle.
  • html.DavFS has a new property cache for caching list results.
  • html.DavFS has a new property fetchManager for using a low.FetchManager instance.
  • The click event of html.MouseBox reports the pressed buttons now.

September 2021

  • html.TextArea has new methods eraseAt, insertAt, positionAt, and setCursor.
  • The function fengshui.load returns a Promise object now.
  • html.FpsMeter has new property manual and method takeFrame for manual frame counting.
  • The await keyword may now be used in JavaScript sections of Shui files.
  • html.Item has the new property aspectRatio for maintaining a fixed aspect ratio when resizing an element.
  • There is a new element ui.Tooltip for tooltips.
  • The property inputDevice of html.Document shows the state keyboard now during keyboard-based navigation.
  • html.Item has new properties maxWidth and maxHeight.
  • Improved performance of element creation.

August 2021