v0.3.0-alpha.44 - The Decorator Future

What's Changed

• feat: add missing active prop for cameras in JSX types by @trusktr in #302
• feat: Dynamic cam by @keywizzle in #304
  • Adds a new dynamic-dolly boolean attribute to <lume-camera-rig>. When true, the effective dolly speed will be changed based on the camera's distance to minDistance. Getting closer to minDistance will lower the effective dolly speed towards zero. This is useful when zoomed into an object and having the dolly movements not be disproportionately huge while viewing fine details of the object.
  • Adds a new dynamic-rotation boolean attribute to <lume-camera-rig>. When true, the effective rotation speed will be changed based on the camera's distance to minDistance. Getting closer to minDistance will lower the effective rotation speed to allow for finer control. This is useful zoomed in to see fine details of an object and having the rotation not be disproportionately huge, for example when zooming into a 3D globe.
• feat: Update lowclass, @lume/element, and three versions (@types/three and three were updated in yarn.lock) by @trusktr in #313
  • This is inherited from the respective changes in @lume/element and in classy-solid, see those release notes in case you're using those libraries directly (which are re-exported from lume, the exports Element, element, attribute, numberAttribute, booleanAttribute, stringAttribute, reactive, and signal)
  • This enables accessor #private fields and get #private/set #private properties to be decorated with @signal, which allows converting code using conventional underscored "private" properties like this,

    @element('my-el')
    class MyEl extends Element3D {
      @signal __someProperty = 123
      
      @signal
      get __otherProperty() {...}
      set __otherProperty(v) {...}
    }

    to code that uses actually-private syntax:

    @element('my-el')
    class MyEl extends Element3D {
      @signal accessor #someProperty = 123
    
      @signal get #otherProperty() {...}
      @signal set #otherProperty(v) {...}
    }

  • BREAKING: If you get an error like Uncaught SyntaxError: The requested module 'lowclass' does not provide an export named 'Constructor', it means your app is loading an older version of lume, @lume/element, classy-solid, lowclass or another dependency that depends on @lume/element, classy-solid, or lowclass.
    • Ensure you have lume 0.3.0-alpha.44, @lume/element 0.13.x, classy-solid 0.4.x, lowclass 8.x, and any updated versions of other libraries that use the new versions of lume, @lume/element, classy-solid, or lowclass.
  • BREAKING: If you get an error like Uncaught TypeError: Failed to resolve module specifier "lowclass/dist/getInheritedDescriptor.js". Relative references must start with either "/", "./", or "../"., it means your <script type="impormap"> needs to be updated to include an entry for lowclass/.
    • Before:

      <script type="importmap">{
        "imports": {
          ...
          "lowclass": "/node_modules/lowclass/dist/index.js",
          ...
        }
      }</script>

      After

      <script type="importmap">{
        "imports": {
          ...
          "lowclass": "/node_modules/lowclass/dist/index.js",
          "lowclass/": "/node_modules/lowclass/",
          ...
        }
      }</script>

      If you are getting dependencies from a CDN, it would be similar:

      <script type="importmap">{
        "imports": {
          ...
          "lowclass": "https://cdn.jsdelivr.net/npm/[email protected]/dist/index.js",
          "lowclass/": "https://cdn.jsdelivr.net/npm/[email protected]/",
          ...
        }
      }</script>

      Another option is to use JSPM Importmap Generator to generate an importmap (tutorial here).
  • BREAKING: If you extended Lume classes to make new classes, or used @lume/element (whose exports are re-exprted from lume) to make new non-3D elements, and you used an attribute decorator (f.e. @attribute, @numberAttribute, etc) or the @signal decorator on any getter/setter class properties, you will need to ensure that you place the decorators on both the getter and the setter. This code,

    @element('my-el')
    class MyEl extends Element3D {
        @numberAttribute
        get someProperty() {...}
        set someProperty(v) {...}
    
        @booleanAttribute
        @noSignal
        get someProperty() {...}
        set someProperty(v) {...}
    
        @signal
        get otherProperty() {...}
        set otherProperty(v) {...}
    }

    becomes the following, ensuring that decorators are repeated on both getter and setter (new lines or no new lines are style preference):

    @element('my-el')
    class MyEl extends Element3D {
        @numberAttribute get someProperty() {...}
        @numberAttribute set someProperty(v) {...}
    
        @booleanAttribute @noSignal get someProperty() {...}
        @booleanAttribute @noSignal set someProperty(v) {...}
    
        @signal get otherProperty() {...}
        @signal set otherProperty(v) {...}
    }

    or

    @element('my-el')
    class MyEl extends Element3D {
        @numberAttribute
        get someProperty() {...}
        @numberAttribute
        set someProperty(v) {...}
    
        @booleanAttribute
        @noSignal
        get someProperty() {...}
        @booleanAttribute
        @noSignal
        set someProperty(v) {...}
    
        @signal
        get otherProperty() {...}
        @signal
        set otherProperty(v) {...}
    }

Insignificant changes to the repo

• undo the temporary change to local examples importmap by @trusktr in #308

Full Changelog: v0.3.0-alpha.43...v0.3.0-alpha.44

v0.3.0-alpha.43

What's Changed

• update cli to fix it from deleting JSX types in dist/ by @trusktr in #301

Full Changelog: v0.3.0-alpha.42...v0.3.0-alpha.43

v0.3.0-alpha.42 - little by little, good things take time!

What's Changed since v0.3.0-alpha.14

Features

• feature: add "l" and "p" shorthands for "literal" and "proportional" sizeMode values, respectively by @trusktr in #250
  • F.e. <lume-mesh size-mode="l p" size="100 0.5">
• feature: use DOM APIs only on the client, not SSR, by avoiding using DOM APIs at the top level of any module. This allows any SSR code (f.e. Svelte apps, Next/Nuxt, etc) that might be importing lume to not fail. by @trusktr in #250
• feature: individual instance setter methods for <lume-instanced-mesh> as an alternative to attributes/props to avoid recalculating every instance matrix when updating only a single instance by @keywizzle in #265
  • el.setInstanceRotation(index, x, y, z)
  • el.setInstanceScale(index, x, y, z)
  • el.setInstancePosition(index, x, y, z)
  • el.setInstanceColor(index, r, g, b)
• feature: remove inertial slowdown for ScrollFling because modern touchpads already have inertial slowdown, and instead add a lerp towards the current position to smooth it out for mouse wheels by @trusktr in #292
• feature, deprecation: rename Node (which conflicts with the global Node) to Element3D, but leave a deprecated Node class for backwards compat for now by @trusktr in #250

Docs

• docs: Update README.md by @UdayKharatmol in #282
• docs: Update README.md by @bhargavshirin in #286

Infra

• infra: update to Yarn 4.0 by @trusktr in #284
• infra: update lume cli to run tests in the amazing @web/test-runner … by @trusktr in #287

Internal

• internal: replace Promise.resolve().then() with the newer queueMicrotask() by @trusktr in #250
• internal: legacy code cleanup 🎉: remove DeclarativeBase, split into CompositionTracker and ChildTracker classes, move remaining logic to the ImperativeBase base class by @trusktr in #250
• internal: rename ImperativeBase to SharedAPI. by @trusktr in #250
  • BREAKING: If you relied on this class (not recommended) import statements should be renamed.
• internal: remove DOM transform property backfill 🎉 by @trusktr in #250
  • This provides an overall better zoom functionality across all browser and OS combinations.
• internal: add InstancedMesh tests, and some internal updates fixes by @trusktr in #267

New Contributors

• @keywizzle made their first contribution in #265
• @UdayKharatmol made their first contribution in #282
• @bhargavshirin made their first contribution in #286

Full Changelog: v0.3.0-alpha.14...v0.3.0-alpha.42

v0.3.0-alpha.14

show LUME version and github link in console, and inside <lume-scene> elements

v0.3.0-alpha.13

fix projected material behavior cleanup

v0.3.0-alpha.12

Features

• make <lume-camera-rig> attributes reactive instead of accepting only initial values b48b682
• make XYZValues x, y, z properties enumerable bd566f0 c977217
• make <lume-camera-rig> attributes reactive instead of serving only as initial values b48b682
• initial standard-material and physical-material behaviors 59ef61b 5711e8b (expanded from alpha.9)
• PointLight.power property 6cbedf6
• <lume-torus> element, torus-geometry behavior, and docs for other mesh elements db268f9
• reactive .version number property on all elements increments when world matrices of an element and its subtree have been updated 4e555fa
• Scene.physicallyCorrectLights property to enable physically-correct lighting mode. c52628b
• projected-material behaviors for Mesh elements, along with accompanying <lume-texture-projector> elements that project a texture onto meshes, and doc updates 5f3587f
  • demos:
    • https://docs.lume.io/#/api/textures/TextureProjector
    • https://docs.lume.io/#/examples/picture-frame

Fixes

• initial pre-upgrade values on elements were not being honored for properties decorated with the @emits decorator bb02328

Breaking

• removed the @emits decorator, we now officially use the more robust and flexible dependency-tracking reactivity patterns for observing property changes bb02328
• remove valuechanged events from XYZValues and subclasses, no longer re-export @lume/eventful from the index fb7fcb3
  We're going all in on automatic dependency-tracking reactivity and discouraging event patterns except where it makes sense. We'll keep some events around that align with DOM patterns, for example load events for when elements are done loading.

v0.3.0-alpha.10

Features:

• feat: <lume-3ds-model> element to load .3ds files. It works exactly like <lume-fbx-model> and <lume-gltf-model> elements, accepting a src attribute for the asset file path. The only difference is the name of the element. abb9c5a

Breaking changes:

• breaking: update three to 0.139. This doesn't break LUME APIs, but any code relying on element.three to use Three.js objects directly may break, especially code that relies on Geometry APIs because the Geometry class was removed and all geometries that previously extended from Geometry now extend from BufferGeometry. 1e85a50

Full Changelog: v0.3.0-alpha.9...v0.3.0-alpha.10

v0.3.0-alpha.9

Features

• add deltaTime parameter to property functions 32d2942
  f.e. element.rotation = (x, y, z, t, dt) => {...}
• add a ShadowRoot to <lume-camera-rig> to make it possible to position (slot) external children relative to the internal camera (f.e. for HUDs) 55d6f99
• add missing types in base classes for TypeScript users. yay 2f068af
• improve DOM and JSX element types 80bd126
• new <lume-shape> element allows for creating extrudable 2D shapes including the ability to define shapes with SVG path strings 9d3a370 59ef61b
• new <lume-clip-plane> element that allows clipping objects on a plane, along with docs and example 4c834df 6b69d0a 59ef61b
• initial standard-material and physical-material behaviors 59ef61b
• more properties for PhongMaterialBehavior 59ef61b
• add minHorizontalAngle and maxHorizontalAngle to <lume-camera-rig> to control min/max amount of lateral rotation 59ef61b
• new <lume-cube-layout> element makes a layout with 6 areas, one one each side of an invisible cube 59ef61b
• breaking: rename lumeParent to parentLumeElement 59ef61b
• new examples and docs!

Fixes

• fix: scene resize no longer moves camera to wrong position
• fix: removing elements no longer sometimes leaves Three.js object behind still rendering

Deprecations

• deprecate LUME.useDefaultNames() in favor of LUME.defineElements(), deprecate Class.define(name) in favor of Class.defineElement(name) 0a93fdd

Breaking changes

• remove the getter methods we had in place for Transformable and Sizeable properties, as TypeScript now has the ability to define different types for getters and setters of an accessor

  This removes Transformable's .getPosition(), .getRotation(), .getScale(), .getOrigin(), .getAlignPoint(), .getMountPoint(), and .getOpacity(), and Sizeable's .getSize() and .getSizeMode() methods.

  Migration: use the respective properties directly (.position, .rotation, etc)

  f1f7055

• better handling of string values, XYZNumberValues now coerces strings to numbers when setting x, y, or z, which can change behavior of an app in some cases. Migration: make sure you provide numbers, not strings; there is no way to restore old behavior because it was undefined. 79d514f

• renamed lumeParent to parentLumeElement 59ef61b

v0.3.0-alpha.8

This includes updates from v0.3.0-alpha.4 to v0.3.0-alpha.8

Get them while they're hot!

Features

• feat (from alpha.2): add the VisualLayers class adapted from my work at https://discourse.threejs.org/t/multiple-scenes-vs-layers/12503/34. We will soon use this to implement a declarative way for specifying visual layers in HTML markup. bdac4ee
• feat: add a center-geometry boolean attribute to <lume-gltf-model> that when true centers all of the model's geometry at the origin. f1a2856
• feat: add an interactive boolean attribute to <camera-rig> that when false disables user interaction, useful for non-interative positioning of a camera using a camera-rig as the positioning mechanism. 76da7ed
• feat: add fogMode, fogNear, fogFar, and fogColor attributes to <lume-scene> to set a visual fog. 18fe01a
• feat: add a .fogDensity property to Scene to configure fog density with fogMode is expo2. 3e45dd0
• feat: cameraNear and cameraFar properties to control the near and far of a Scene's default camera. e24cdb7
• feat: Pass a second argument to render tasks containing the delta time for convenience. 0051a78
• feat: add a .swapLayers property to Scene to allow the CSS layer to be rendered below the WebGL layer. 762704f
• feat: feat: initial <lume-instanced-mesh> element. We are able to supply instance positions, rotations, and colors via
  properties or attributes of those names, each taking an array of numbers. Attributes accept a string of comma-separated number triplets such as position="1 2 3, 4 5 6, 7 8 9" with each triplet being an X, Y and Z value. ec85416 20b9906

Fixes

• fix: don't forget to remove ScrollFling's and FlingRotation's render tasks (i.e. terminate any animations) on stop(). ded9fe2
• fix: disconnected children were not having their three object removed from rendering. 21f40de
• fix: Firefox has the older version of ResizeObserver without the arrays of size values for column layouts, so LUME was broken in Firefox. Adds a fallback to the non-array contentBoxSize value. 97de8f8
• fix: improve Scene's shadow DOM so that absolutely nothing in there can be interacted with, i.e. no pointer events, etc (it is implementation detail for rendering only). 84762e1

BREAKING CHANGES:

• breaking: A FlingRotation instance no longer automatically starts on construction; the start() method should be called manually after instantiation. 8a1b4b7
• feat / breaking: ShadowDOM composition edge case bugs are fixed, and thus it is finally and officially fully supported, plus new DOM traversal APIs! See more info below. 23033d2 aa25085
• breaking: all Solid.js dependencies updated to v1.0. This may make newer elements incompatible with older elements due to underlying differing compilation outputs depending on different Solid runtimes for HTML/JSX template functionality. 598d1b5 9056944

feat/breaking: ShadowDOM composition edge case bugs are fixed, plus a few new APIs.

Massive cleanup:

Factor out some old code from a few years back, making the tree structure
easier to understand and less error prone. This allowed us to make more sense
of the ShadowDOM composition stuff and to be able to finally polish the
remaining rough edges. 🎉

BREAKING CHANGES:

To clean up the code and finish ShadowDOM composition, we removed some APIs:

• Removed the TreeNode APIs add, addChildren, removeNode,
  removeChildren, removeAllChildren, childCount, subnodes, and
  parent. You must now simply use the actual DOM APIs like append,
  appendChild, remove, removeChild, parentElement, children, etc.
• Removed Scene.mount() and Scene.unmount(). Just use regular DOM APIs to
  append or remove a Scene from the DOM.

Unrelated to ShadowDOM composition, we cleaned up some other things too:

• Removed the old imperativeCounterpart property.
• Renamed _render() to update() because it is called from the outside in
  the Motor class.

The stuff we removed existed for two reasons:

1. The TreeNode APIs (add, removeChild, etc) existed from before we were
   using Custom Elements, just plain JS objects, so we needed our own tree API
   in order to create our scene graph
2. When we added support for Custom Elements, we initially had two trees, the
   DOM tree and our own scene graph tree. Our tree had all the logic and the
   DOM tree was merely an interface that proxied data to/from our tree. The
   idea was that a plain JS user could use our tree APIs in non-DOM
   environments, and DOM users could use the custom element tree. We have since
   merged the two trees so our LUME objects are also the custom elements
   themselves. With removal of our old TreeNode APIs, we can later support
   non-DOM environments by instead polyfilling some of the DOM tree APIs as
   needed in those environments.

Other new features:

feat: Added new APIs that are LUME-specific and complementary to DOM APIs:

• .lumeParent - Get the parent element of the current LUME element only if
  the parent is a LUME element. Returns null if there is no DOM parent, or if
  the DOM parent is not a LUME element.
• .lumeChildren - Get the child LUME elements of the current LUME element.
  This ignores any DOM children that are not LUME elements; those elements will
  not be included in the result array.
• .lumeChildCount - Get the count of child LUME elements of the current LUME
  element. This ignores child elements that are not LUME elements.
• composedLumeParent - The composed parent LUME element (based on the composed tree) of the current LUME element.
• composedLumeChildren - The composed child LUME elements (based on the composed tree) of the current LUME element.
• .traverseSceneGraph(visitorFn) - Traverses the composed tree of LUME
  elements in pre-order. The tree that this traverses is the tree that is
  composed from the hierarchy of ShadowRoot trees with elements distributed
  through those trees via slot elements.

In these new APIs, non-LUME elements are ignored similarly to how some regular
DOM APIs ignore text nodes (.children, .parentElement, .assignedElements,
etc). To certain LUME elements like <lume-node> or <lume-mixed-plane>,
non-LUME HTML elements and text nodes are merely content that render on their
rectangular flat surface, and those non-LUME elements are not part of the
hierarchy of 3D objects, so these new APIs make it easier to traverse LUME elements
while ignoring the rest.

In a new light! (v0.3.0-alpha.3)

New features

• New lambert-material behavior. 7971563
• New <lume-direction-light> element for defining directional lighting. 1ffd181