Description

This pull request is about adding support for hooks, a feature similar to React Hooks.

I won't go into details, feel free to check react docs on hooks for following along.

Primary goal of this pull request is to provide a standard interface for hooks which users can use to create their own hooks. Of course we'll provide few hooks as an example but our focus is more on facilitating easy yet powerful hook implementations that can be created externally.

Hooks

First things first,

A FunctionWidget/WidgetFunction is a function that returns a widget:

Widget widgetFunction() {
  return Span(
      child: Text('hello world'),
    );
}

runApp(app: widgetFunction(), ...);

Functions as such are stateless and yeild same output everytime they get called.

Hooks can powerup these functions by letting you use state and other features inside functions.

Implementation

I've tried couple of ways:

Method 1(with context + a wrapper widget)

Widget widgetFunction() => HooksWrapperWidget((context) {
  var state = context.useState(0);

  return Span(
    child: Text('You clicked me ${state.value} time!'),
    onClick: (_) => state.value++,
  ); 
});

runApp(app: widgetFunction(), ...);

This is without a doubt, the most reliable and safest way one can use hooks.

While this is safe it suffers from other problems. Here hooks are tightly coupled with the context and this limits them to whatever a particular context is limited to. Users who will be using hooks probably looking for something easy to reuse and extend even if it takes away few guarantees so let's see a little bit unsafe method:

Method 2

Widget widgetFunction() => HookScope(() {
  var state = useState(0);

  return Span(
    child: Text('You clicked me ${state.value} time!'),
    onClick: (_) => state.value++,
  ); 
});

runApp(app: widgetFunction(), ...);

This is what we're going to implement. Here, both HookScope and useState are not tied with each other and can be implemented independently, which basically means,

• Users can easily implement their own hooks.
• Users can easily use hooks implemented by the others.

How this works?

Similar to React, we'll rely on the order in which hooks are executed.

This puts few responsibilities on the users:

1. Users should always wrap their WidgetFunction in HookScope.
2. Users should not call Hooks inside loops, conditions, or nested functions.
3. Users should use Hooks at the top level of their functions, before any widget/or early return.

We'll try to throw errors or warn users where we can but just know that these rules applies to React as well(read more).

Progress

I've already got a prototype working. I'll outline a slightly different implementation(that of course can change):

• [x] Add hook and scope interface
• [x] Add dispatcher methods
• [x] Add a standard implementation for scope(HookScope)

Rad Hooks

• [x] Add useContext
• [x] Add useNavigator

React Hooks

• [x] Add useRef
• [x] Add useState
• [x] Add useEffect
• [x] Add useLayoutEffect
• [x] Add useMemo and useCallback

Benchmark results

Hopefully we won't be making any changes to core/existing-widgets so there will be no need.

Hi, thanks for you work!

I have been building the web bootstrap components bindings in this repo. At the moment it supports three different frameworks: deact, jaspr and rad. I have implemented bindings for each of the frameworks separately in different packages. You can view all the implemented bootstrap components in the deployed page, that page renders the components with package:deact. Another deact example is this one and a jaspr example is this one. At the moment, I have not implemented any rad examples.

Maybe it would be nice to collaborate on a shared interface between the Dart web frameworks, perhaps something similar to what bootstrap_dart is doing, but where the libraries implement them natively. You can view the Dart interface in the readme of the repo.

Perhaps a "web_rendering_interface" package that exposes interfaces like Ref, State, BuildContext, Component, some base hooks, and the ability to render HTML elements, text nodes and fragments (List of Components) could be used. The rendering packages (deact, jaspr or rad) implement these interfaces and the component packages (or logic packages such as for hooks or routing) use those interfaces.

At the moment, bootstrap_dart uses a global BoostrapRenderer instance that has to be overridden to use the renderer for each package like this example that executes this function. The returned components are of type dynamic, which works, but maybe isn't great. BoostrapRenderer has a generic type parameter for the component type which could be used to improve type safety. For type safety, the BoostrapRenderer in the repo could use extensions to implement the components and the BoostrapRenderer instance could be used directly (boostrapRenderer.card(...) to return a Card bootstrap component). The extensions would need to be imported since they contain the implementation for each component. Or perhaps we could expose a Component interface in "web_rendering_interface" so that the component libraries return an instance of that interface. Or reimplement each component in all the packages that interface the rendering framework with the component libraries, perhaps with code generation to maintain documentation and the API synched.

This would allow for the component libraries to use the same code and interface with multiple different rendering libraries. As well as perhaps share hooks between different frameworks. This could also be extended to other functionalities like server side rendering, routing or dependency injection. Where the routing logic could be used for every rendering package.

Thanks for reading!

I dag into what you did here and overall, I really like some of the things I see. With my appreciation to the effort you put into making this happen, there are some areas that I think could benefit from a bit more attentive coding love :)

GJ, so far, I hope you keep on going!

Statics - testability - multiple apps

1. _registeredWidgetObjects is static in framework.dart - multiple instances an app is a no-go?
   • you are protecting against multiple FW instances with checking _isInit value
   • An app should probably run in its own zone to make sure that errors from one doesn't break others, in case you enable multiple app to run on the same page (there are some nice use-cases for this)
   • Maybe, a similar "bootstrapping" mechanism can be used as seen in Flutter runApp(RadApp, someOptions) to init logging, debug tooling, zones, etc.
2. statics effectively prevent tests to mock out pieces of the FW - make it very tedious

Navigator and routes

This is tough one. Angular didn't get it right the first time, nor did Flutter. No surprises here :)

2. window.addEventListener("popstate" could be written as window.onPopState.listen
   • listeners should be disposed when app is disposed
3. Navigator doesn't seem to react to manual command in console history.pushState({}, '', 'another')
   • this prevents being able to react to external changes, maybe 3rd party libraries
4. In local development, using path based routing is cumbersome. In debug mode, it should be permissible to use hash routes. eg. localhost:8080/#/home
5. sitemap is still a thing, there should be a mechanism in place to extract route information
   • one thing that pops into mind is compile time const expressions for routes
6. Routes should be allowed to be loaded async with deffered as import statements
   • AsyncRoute subclass maybe?
   • or maybe instead of page, there could be a AsyncWidgetBuilder callback for the Route with FutureOr return value?
7. There is a seemingly arbitrary restriction what a path might look like for a Route: RegExp(r'^[a-zA-Z0-9_]+$'). Is there a reason for this?
   • with that routes such as this would be not possible /blog/some-blog-entry-title-sanitized'
8. Is there a way to capture paths as params to a Route? eg. /blog/:slug:

Events and event handling

I noticed that there isn't really a consistent handling of events across the widgets. Most, if not all, have an onClickEventListener and there is GestureDetector widget. There are important use-cases that I can't cover with these 2.

There is one workaround I found: using a stateful widget where I get to access the DOM element from initState and go underneath the FW.

  late StreamSubscription sub;

  void initState() {
    sub = element.onMouseEnter.listen((event) {
      print('${(event.currentTarget! as Element).text}');
    });
  }

  void dispose() {
    sub.cancel();
  }

While this works, it feels out of place. A way to automagically handle stream subscriptions and their disposals would be beneficial.

Maybe something along these lines?

class MouseEnterSample extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Handle(
      events: {
        'mouseEnter': enterHandler,
        'my-custom-event', customHandler,
      },
      child: MyButton,
    );
  }
}

Hi, thanks for your work!

I found that when I pass an empty String to the InputText widget constructor, the text is not cleared. The value of the element is not overridden. Should I save the dart:html.InputElement reference to clear and update the value, like a Flutter TextEditingController?

I was also wondering whether a void Function(String value) onValueChange argument in the constructor could be used as API, maybe the same for others where we know the Dart type such as number or date inputs. At the moment I was casting the event target to dart:html.InputElement and accessing the value from that. However, for InputText and others we know the element and type of input (and Dart's value type).

The full code that I was testing is in this file.

Thanks again!

In my app I would like to give the output of a calculation as a longer Text in a readonly TextArea, so that it is easy to select and copy the content. But I find no way to define a value in the TextArea constructor:

TextArea(
            placeholder: 'Dart output',
            readOnly: true,
            maxLength: 9999,
            classAttribute: 'w-full h-96 border mt-4 p-2',
            innerText: outputVariable,
          )

I can only define the innerText but this is not the value. I can access the TextArea with document.getElementById and then change the value property but after a setState this is lost.

For HTML Widgets we can define classes in Rad by using the classAttributes. This maps to the classNames attribute of HtmlElements in dart:html. But in HtmlElements we also have the classes parameter where we can use an Iterable. By using a Set there we have some advantages:

The list of class is easier to read. Especially when using tailwindCSS we will have much cleaner code.

Compare:

class EmptyView extends StatelessWidget {
  final String text;

  EmptyView({required this.text});

  @override
  Widget build(context) {
    return Division(
      classAttribute: 'w-full h-full justify-center items-center flex',
      children: [
        Division(
          classAttribute: 'p-4 text-center text-sm text-gray-600',
          innerText: text,
        )
      ],
    );
  }
}

To:

import 'dart:html';

import 'package:rad/rad.dart';
import 'package:rad/widgets_html.dart';

class EmptyView extends StatelessWidget {
  final String text;

  EmptyView({required this.text});

  @override
  Widget build(context) {
    return Division(
      classes: {
        'w-full',
        'h-full',
        'justify-center',
        'items-center',
        'flex',
      },
      children: [
        Division(
          classes: {
            'p-4',
            'text-center',
            'text-sm',
            'text-gray-600',
          },
          innerText: text,
        )
      ],
    );
  }
}

Also by using Sets we make sure that we can't pass the same class multiple times.

Proposal: We could replace String classAttribute with Iterable<String> classes or we add classes as an additional attribute and define what happens if the user uses both.

Hi, At the moment the problem I was having (shown here) was accessing the exact key pressed in a InputText to send a message when the user presses the "Enter" key. I was wondering whether there is a way to access the inner _rawEvent or perhaps other API for accessing the dart:html event. Or maybe I could not find it in the docs and code?

Thank you for your work!

Everything works very clearly.
But the typos hurt the eyes. I recently installed (in vscode) an add-on and it shows all the typos.

Eg.

P.S. I use Code Spell Checker But this only works in files opened in the editor.

This pull request contains:

1. RenderEvents, a event system for RenderElements.
2. Couple of optimizations, major one being the ability to short-circuit dispose(s) using RenderEvents.

Render events

RenderEvents are the events that framework will emit when it interacts with a RenderElement. Just like we can add event listeners for user interactions on DOM elements, we can now add event listeners for framework interactions on RenderElements. Similar to DOM events, we've different types of RenderEvents for different types of interactions which are listed below:

• didRender is a event that's emitted after framework finishes rendering the output of render to the DOM.
• didUpdate is a event that's emitted after framework finishes rendering the output of update to the DOM.
• willUnMount is a event that's emitted when framework is about to remove the widget from the DOM.
• didUnMount is a event that's emitted after framework finishes removing the widget from the DOM.

RenderElements can decide to listen to a particular or all render events by adding event listeners.

Comparing RenderEvents with DOM events, there are few differences & restrictions:

• RenderEvents do not have capture/bubble phase.
• RenderEvents are meant to be listened internally inside RenderElements.
• Listeners for RenderEvents can be attached only during initial render, and cannot be updated.

These restrictions are temporary and we'll lift them when needed.

RenderEvents are meant to solve the problem of limited control over lifecycle in RenderElements. Previously we were providing a sub-class WatchfulRenderElement with hardcoded lifecycle. Now, using the new RenderEvents API, users can add as much or as little lifecycle as they want, to any RenderElement(widget). This new API effectively makes WatchfulRenderElement obsolete(but we'll keep it for backward compatibility).

Benchmark results

• RenderEvents (prototype) vs 1.1.0 (1)
• RenderEvents (prototype) vs 1.1.0 (2)
• RenderEvents (prototype) vs 1.1.0 (3)
• RenderEvents (prototype) vs RenderEvents (final) (1)
• RenderEvents (prototype) vs RenderEvents (final) (2)

I just tried this package and I love it! It seems like a great alternative to https://github.com/schultek/jaspr (both project have their pros and cons of course)

However, it would be great to have support for static site generation in Rad, to be able to generate static html pages from my dart code.

Description

This pull request is about adding Refs support in Rad's HTML widgets.

Providing 'a declarative way' for everything sounds great but hard to accomplish. There are number of cases where users simply want the framework to get out of their way. We already provide few escape hatches like RawMarkUp widget but sometimes users want to access DOM elements that are associated with HTML widgets. Rather than forcing users to go underneath the framework ( document.getElementById ), we should provide a much easy and predictable way i.e Refs.

This feature is similar to React's Refs but with few differences:

• Only callback Refs, no legacy string/createRef APIs.
• Only on HTML widgets(we want refs to be a feature of widget not framework)

Progress

Update: With the support for RenderEvents(v1.2.0), we can add Refs without adjusting anything in the core.

• [x] Implement Refs in HTML base widget.
• [x] Add ref property to all HTML widgets(only HTML widgets, for now).

Benchmark results

• [x] Benchmark results: vs 1.0.1 | vs 1.1.0 - [old results]

Updated Benchmark results

• [x] HTML Refs(final) vs 1.2.0 (1)
• [x] HTML Refs(final) vs 1.2.0 (2)
• [x] HTML Refs(final) vs 1.2.0 (3)

This pull request:

• Reduces coupling between Navigator widget and Router service.
• Fixes: Router is incorrectly pushing the Route.name to the address bar instead of the Route.path.
• Fixes: When NavigatorState.open is called inside Navigator.onInit, it can result in multiple routes being left open.