@manyducks.co/dolla 2.0.0-alpha.9 → 2.0.0

package/dist/typeChecking.d.ts

@@ -1,8 +1,8 @@
-type TypeNames = "string" | "number" | "bigint" | "boolean" | "symbol" | "undefined" | "object" | "function" | "null" | "array" | "class" | "promise" | "NaN";
+type TypeNames = "string" | "number" | "bigint" | "boolean" | "symbol" | "undefined" | "object" | "function" | "null" | "array" | "class" | "promise" | "map" | "set" | "NaN";
 /**
  * Extends `typeof` operator with more specific and useful type distinctions.
  */
-export declare function typeOf(value: unknown): TypeNames;
+export declare function typeOf(value: any): TypeNames;
 /**
  * Throws a TypeError unless `condition` is truthy.
  *
@@ -18,12 +18,6 @@ export declare function isArray(value: unknown): value is Array<unknown>;
  * Throws an error if `value` is not an array.
  */
 export declare function assertArray(value: unknown, errorMessage?: string): value is Array<unknown>;
-/**
- * Returns a function that takes a `value` and ensures that it is an array for which `check` returns true for every item.
- *
- * @param check - Function to check items against.
- */
-export declare function isArrayOf<T>(check: (item: unknown) => boolean): (value: unknown) => value is T[];
 /**
  * Returns true when `value` is an array and `check` returns true for every item.
  *
@@ -31,12 +25,6 @@ export declare function isArrayOf<T>(check: (item: unknown) => boolean): (value:
  * @param value - A possible array.
  */
 export declare function isArrayOf<T>(check: (item: unknown) => boolean, value: unknown): value is T[];
-/**
- * Returns a function that takes a `value` and throws a TypeError unless it is an array for which `check` returns true for every item.
- *
- * @param check - Function to check items against.
- */
-export declare function assertArrayOf<T>(check: (item: unknown) => boolean): (value: unknown) => value is T[];
 /**
  * Throws a TypeError unless `value` is an array and `check` returns true for every item.
  *
@@ -45,14 +33,6 @@ export declare function assertArrayOf<T>(check: (item: unknown) => boolean): (va
  * @param errorMessage - A custom error message.
  */
 export declare function assertArrayOf<T>(check: (item: unknown) => boolean, value: unknown, errorMessage?: string): value is T[];
-/**
- * Returns true if `value` is equal to `true` or `false`.
- */
-export declare function isBoolean(value: unknown): value is boolean;
-/**
- * Throws a TypeError unless `value` is equal to `true` or `false`.
- */
-export declare function assertBoolean(value: unknown, errorMessage?: string): value is boolean;
 /**
  * Returns true if `value` is a string.
  */
@@ -77,34 +57,6 @@ export declare function isNumber(value: unknown): value is number;
  * Throws a TypeError unless `value` is a number.
  */
 export declare function assertNumber(value: unknown, errorMessage?: string): value is number;
-/**
- * Returns true if `value` implements the Promise protocol.
- * This matches true instances of Promise as well as any object that
- * implements `next`, `catch` and `finally` methods.
- *
- * To strictly match instances of Promise, use `isInstanceOf(Promise)`.
- */
-export declare function isPromise<T = unknown>(value: unknown): value is Promise<T>;
-/**
- * Throws a TypeError unless `value` implements the Promise protocol.
- * This matches true instances of Promise as well as any object that
- * implements `next`, `catch` and `finally` methods.
- *
- * To strictly allow only instances of Promise, use `Type.assertInstanceOf(Promise)`.
- */
-export declare function assertPromise<T = unknown>(value: unknown, errorMessage?: string): value is Promise<T>;
-/**
- * Returns true if `value` is a class.
- */
-export declare function isClass(value: unknown): value is {
-    new (): unknown;
-};
-/**
- * Throws a TypeError unless `value` is a class.
- */
-export declare function assertClass(value: unknown, errorMessage?: string): value is {
-    new (): unknown;
-};
 /**
  * Returns a function that takes a `value` and returns true if `value` is an instance of `constructor`.
  *
@@ -132,30 +84,6 @@ export declare function assertInstanceOf<T extends Function>(constructor: T): (v
  * @param errorMessage - A custom error message for when the assertion fails.
  */
 export declare function assertInstanceOf<T extends Function>(constructor: T, value: unknown, errorMessage?: string): value is T;
-/**
- * Returns true if `value` is a Map.
- */
-export declare function isMap<K = unknown, V = unknown>(value: any): value is Map<K, V>;
-/**
- * Throws a TypeError unless `value` is a Map.
- */
-export declare function assertMap<K = unknown, V = unknown>(value: any, errorMessage?: string): value is Map<K, V>;
-/**
- * Returns true if `value` is a Set.
- */
-export declare function isSet<T = unknown>(value: any): value is Set<T>;
-/**
- * Throws a TypeError if `value` is not a Set.
- */
-export declare function assertSet<T = unknown>(value: any, errorMessage?: string): value is Set<T>;
-/**
- * Returns true if `value` implements the Iterable protocol.
- */
-export declare function isIterable<T>(value: any): value is Iterable<T>;
-/**
- * Throws a TypeError unless `value` implements the Iterable protocol.
- */
-export declare function assertIterable<T>(value: any, errorMessage?: string): value is Iterable<T>;
 /**
  * Returns true if `value` is a plain JavaScript object.
  */
@@ -164,28 +92,4 @@ export declare function isObject(value: unknown): value is Record<string | numbe
  * Throws a TypeError unless `value` is a plain JavaScript object.
  */
 export declare function assertObject(value: unknown, errorMessage?: string): value is object;
-/**
- * Returns true if `value` is equal to `null`.
- */
-export declare function isNull(value: unknown): value is null;
-/**
- * Throws a TypeError unless `value` is equal to `null`.
- */
-export declare function assertNull(value: unknown, errorMessage?: string): value is null;
-/**
- * Returns true if `value` is equal to `undefined`.
- */
-export declare function isUndefined(value: unknown): value is undefined;
-/**
- * Throws a TypeError unless `value` is equal to `undefined`.
- */
-export declare function assertUndefined(value: unknown, errorMessage?: string): value is undefined;
-/**
- * Returns true if `value` is equal to `null` or `undefined`.
- */
-export declare function isEmpty(value: unknown): value is void;
-/**
- * Throws a TypeError unless `value` is equal to `null` or `undefined`.
- */
-export declare function assertEmpty(value: unknown, errorMessage?: string): value is void;
 export {};

package/dist/typeChecking.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types.d.ts

@@ -1,17 +1,30 @@
 import type * as CSS from "csstype";
-import { Ref, type Markup } from "./markup.js";
-import { SettableState, State } from "./state.js";
+import type { Markup, MarkupNode } from "./core/markup.js";
+import type { Signal } from "./core/signals.js";
+export type Env = "production" | "development";
 /**
  * Represents everything that can be handled as a DOM node.
  * These are all the items considered valid to pass as children to any element.
  */
-export type Renderable = string | number | Markup | false | null | undefined | State<any> | (string | number | Markup | false | null | undefined | State<any>)[];
-export type Stringable = {
-    toString(): string;
-};
-type MaybeState<T> = T | State<T> | State<T | undefined>;
-type OptionalProperty<T> = T | State<T> | State<T | undefined>;
-type RequiredProperty<T> = T | State<T>;
+export type Renderable = string | number | Node | Markup | MarkupNode | false | null | undefined | Signal<any> | (string | number | Node | Markup | MarkupNode | false | null | undefined | Signal<any>)[];
+export interface BaseProps {
+    children?: Renderable;
+}
+/**
+ *
+ */
+export type View<Props> = (props: Props) => Renderable;
+/**
+ *
+ */
+export type Store<Options, Value> = (options: Options) => Value;
+/**
+ *
+ */
+export type Mixin<E extends Element = Element> = (element: E) => void;
+type MaybeSignal<T> = T | Signal<T> | Signal<T | undefined>;
+type OptionalProperty<T> = MaybeSignal<T>;
+type RequiredProperty<T> = T | Signal<T>;
 type AutocapitalizeValues = "off" | "on" | "none" | "sentences" | "words" | "characters";
 type ContentEditableValues = true | false | "true" | "false" | "plaintext-only" | "inherit";
 type ClassListValues = string | ClassMap | Array<string | ClassMap | (string | ClassMap)[]>;
@@ -23,21 +36,31 @@ type InputModeValues = "decimal" | "email" | "none" | "numeric" | "search" | "te
  * Properties common to all Elements.
  */
 export interface ElementProps {
+    /**
+     * Sets the value as an HTML attribute.
+     */
+    [key: `attr:${string}`]: OptionalProperty<any>;
+    /**
+     * Sets the value directly on the HTMLElement as a property.
+     */
+    [key: `prop:${string}`]: OptionalProperty<any>;
+    /**
+     * Attaches an event listener to the element (with `addEventListener`).
+     */
+    [key: `on:${string}`]: OptionalProperty<EventHandler<Event>>;
     /**
      * HTML attributes to assign to the element.
      */
-    attributes?: OptionalProperty<Record<string, any>>;
     /**
      * Object of event listeners.
      */
-    eventListeners?: OptionalProperty<Record<string, EventHandler<Event>>>;
     /**
      * CSS classes to be applied to this element. In addition to the standard space-separated list of class names,
      * this property also supports a class map object with class names as keys and booleans as values.
      * Class names in a class map will be applied to the element while their values are true. Also supports an
      * array of strings and class maps.
      *
-     * Alias of `className`.
+     * @alias className
      *
      * @example
      * <div class="one-class" />
@@ -57,6 +80,8 @@ export interface ElementProps {
      * Class names in a class map will be applied to the element while their values are true. Also supports an
      * array of strings and class maps.
      *
+     * @alias class
+     *
      * @example
      * <div className="one-class" />
      *
@@ -71,22 +96,39 @@ export interface ElementProps {
     className?: OptionalProperty<ClassListValues>;
     /**
      * A unique string to identify this element.
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/id
      */
     id?: OptionalProperty<string>;
+    /**
+     * Renders a string of HTML as the children of this element.
+     * Equivalent to setting `innerHTML` on a DOM element.
+     *
+     * `NOTE` This property does no sanitization. If it's in the string, it's in the DOM. Be mindful when handling user-generated content.
+     */
+    innerHTML?: OptionalProperty<string>;
+    /**
+     * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/popover
+     */
+    popover?: OptionalProperty<"auto" | "hint" | "manual" | true | false>;
+    /**
+     * Specifies the element's [WAI-ARIA role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles).
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/role
+     */
+    role?: OptionalProperty<string>;
     /**
      * Scroll position from the left (on the X axis), if this element is scrollable.
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollLeft
      */
     scrollLeft?: OptionalProperty<number>;
     /**
      * Scroll position from the top (on the Y axis) if this element is scrollable.
-     */
-    scrollTop?: OptionalProperty<number>;
-    /**
-     * Enables or disables checking for spelling errors in an element's content.
      *
-     * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/spellcheck
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollTop
      */
-    spellcheck?: OptionalProperty<boolean>;
+    scrollTop?: OptionalProperty<number>;
     /**
      * Specifies whether an element's content should be translated when the page is localized.
      *
@@ -105,12 +147,18 @@ export interface ElementProps {
      * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/slot
      */
     slot?: OptionalProperty<string>;
+    /**
+     * Enables or disables checking for spelling errors in an element's content.
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/spellcheck
+     */
+    spellCheck?: OptionalProperty<boolean>;
     /**
      * Inline styles applied to the element. Can be passed as a string or as an object.
      *
      * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style
      */
-    style?: string | CSSProperties | State<string> | State<CSSProperties> | State<string | CSSProperties> | State<string | undefined> | State<CSSProperties | undefined> | State<string | CSSProperties | undefined>;
+    style?: string | CSSProperties | Signal<string> | Signal<CSSProperties> | Signal<string | CSSProperties> | Signal<string | undefined> | Signal<CSSProperties | undefined> | Signal<string | CSSProperties | undefined>;
     /**
      * Fired when a CSS animation unexpectedly aborts.
      *
@@ -178,6 +226,12 @@ export interface ElementProps {
      * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/compositionupdate_event
      */
     onCompositionUpdate?: OptionalProperty<EventHandler<CompositionEvent>>;
+    /**
+     * Fired when the user attempts to open a context menu. Typically triggered by clicking the right mouse button.
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/contextmenu_event
+     */
+    onContextMenu?: OptionalProperty<EventHandler<PointerEvent>>;
     /**
      * Fired when a pointing device button is rapidly clicked twice while the pointer is inside the element.
      *
@@ -452,6 +506,12 @@ export interface ElementProps {
      * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/compositionupdate_event
      */
     oncompositionupdate?: OptionalProperty<EventHandler<CompositionEvent>>;
+    /**
+     * Fired when the user attempts to open a context menu. Typically triggered by clicking the right mouse button.
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/contextmenu_event
+     */
+    oncontextmenu?: OptionalProperty<EventHandler<PointerEvent>>;
     /**
      * Fired when a pointing device button is rapidly clicked twice while the pointer is inside the element.
      *
@@ -683,6 +743,12 @@ export interface HTMLElementProps extends ElementProps {
      * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/contentEditable
      */
     contentEditable?: OptionalProperty<ContentEditableValues>;
+    /**
+     * Stores values on the element as attributes prefixed with `data-`.
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/dataset
+     */
+    dataset?: OptionalProperty<Record<string, string>>;
     /**
      * Specifies text directionality of the content of this element. Some languages, such as Arabic, are written from right to left (specified here as "rtl").
      *
@@ -729,7 +795,6 @@ export interface HTMLElementProps extends ElementProps {
     /**
      * TODO: Add support. Currently experimental.
      */
-    role?: OptionalProperty<string>;
     /**
      * This element's position in the tab order, or the order this element will be focused as the user cycles through elements with the tab key.
      *
@@ -938,6 +1003,10 @@ export interface HTMLElementProps extends ElementProps {
     onpaste?: OptionalProperty<EventHandler<ClipboardEvent>>;
 }
 export interface SVGElementProps extends ElementProps {
+    /**
+     * A mixin function or an array of mixin functions to be applied to this element.
+     */
+    mixin?: Mixin<SVGElement> | Mixin<SVGElement>[];
 }
 /**
  * Mapping of event props to event names.
@@ -1210,7 +1279,7 @@ export type CSSProperties = {
     [K in keyof Styles]: OptionalProperty<Styles[K]>;
 };
 export interface ClassMap {
-    [className: string]: MaybeState<any>;
+    [className: string]: MaybeSignal<any>;
 }
 export type EventHandler<E> = (event: E) => void;
 export interface PropertiesOf<E extends HTMLElement> extends HTMLElementProps {
@@ -1221,7 +1290,11 @@ export interface PropertiesOf<E extends HTMLElement> extends HTMLElementProps {
     /**
      * Receives a reference to the DOM node when rendered.
      */
-    ref?: Ref<E> | Ref<HTMLElement> | Ref<Element> | Ref<Node>;
+    ref?: ((value: E | undefined) => void) | ((value: HTMLElement | undefined) => void) | ((value: Element | undefined) => void) | ((value: Node | undefined) => void);
+    /**
+     * A mixin function or an array of mixin functions to be applied to this element.
+     */
+    mixin?: Mixin<E> | Mixin<E>[];
 }
 /**
  * The following elements are defined based on the WHATWG HTML spec:
@@ -2098,7 +2171,7 @@ interface HTMLMediaElementProps<T extends HTMLMediaElement> extends HTMLElementP
      *
      * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/srcObject
      */
-    srcObject?: MediaStream | MediaSource | Blob | File | State<MediaStream> | State<MediaStream | undefined> | State<MediaSource> | State<MediaSource | undefined> | State<Blob> | State<Blob | undefined> | State<File> | State<File | undefined>;
+    srcObject?: MediaStream | MediaSource | Blob | File | Signal<MediaStream> | Signal<MediaStream | undefined> | Signal<MediaSource> | Signal<MediaSource | undefined> | Signal<Blob> | Signal<Blob | undefined> | Signal<File> | Signal<File | undefined>;
     /**
      * The current audio volume of the media element. Must be a number between 0 and 1.
      *
@@ -2597,7 +2670,7 @@ interface HTMLImageElementProps extends PropertiesOf<HTMLImageElement> {
      *
      * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/sizes
      */
-    sizes?: MaybeState<string>;
+    sizes?: MaybeSignal<string>;
     /**
      * The image URL.
      *
@@ -3143,7 +3216,6 @@ interface HTMLInputElementProps extends PropertiesOf<HTMLInputElement> {
     step?: OptionalProperty<number>;
     type?: OptionalProperty<InputType>;
     value?: OptionalProperty<string>;
-    $$value?: SettableState<any>;
     width?: OptionalProperty<string | number> | OptionalProperty<string> | OptionalProperty<number>;
     title?: OptionalProperty<string>;
     /**

package/dist/utils.d.ts

@@ -1,5 +1,19 @@
 export declare const noOp: () => void;
-export declare function deepEqual(one: any, two: any): boolean;
+export declare function getUniqueId(): string;
+export declare function getIntegerId(): number;
+/**
+ * Equality check that passes if both values are the same object.
+ * This is the default equality check for states.
+ */
+export declare function strictEqual(a: any, b: any): boolean;
+/**
+ * Equality check that passes if both values are the same object, or if both are objects or arrays with equal keys and values.
+ */
+export declare function shallowEqual(a: any, b: any): boolean;
+/**
+ * Equality check that passes if two objects have equal values, even if they are not the same object.
+ */
+export declare function deepEqual(a: any, b: any): boolean;
 /**
  * Takes an old value and a new value.  Returns a merged copy if both are objects, otherwise returns the new value.
  */
@@ -13,8 +27,16 @@ export declare function merge(one: unknown, two: unknown): any;
  * @param object - An object to clone without the omitted keys.
  */
 export declare function omit<O extends Record<any, any>>(keys: (keyof O)[], object: O): Record<any, any>;
-export declare function getDefaultConsole(): any;
-export declare function colorFromString(value: string): string;
+export declare function toArray<T>(value: T | T[]): T[];
+export declare function toCamelCase(s: string): string;
+/**
+ * Moves an element using `moveBefore` if the browser supports it, otherwise falls back to `insertBefore`.
+ */
+export declare function moveBefore(parent: Node, node: Node, child: Node | null): void;
+/**
+ * Takes any string and returns an OKLCH color.
+ */
+export declare function okhash(value: string): string;
 export type MatcherFunction = (value: string) => boolean;
 /**
  * Parses a filter string into a matcher function.

package/docs/buildless.md

@@ -0,0 +1,132 @@
+# Going Buildless: The No-Stress Setup
+
+Aight, so we've been talking about setting up Dolla with Vite, which is sick for real projects. But what if you just wanna vibe? What if you wanna throw together a quick demo on CodePen, or just mess around in a single HTML file without all the setup drama?
+
+Bet. You can totally run Dolla **buildless**. No npm, no Vite, no `tsconfig.json`. Just you, a browser, and an HTML file.
+
+The magic that makes this happen is a tiny library called [HTM (Hyperscript Tagged Markup)](https://github.com/developit/htm). It's basically JSX, but for the browser. It lets you write your UI using tagged template literals, which look a little weird at first but are actually super intuitive.
+
+## The Setup: One HTML File to Rule Them All
+
+Fr, this is all you need. Just create an `index.html` file and paste this in.
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Dolla Buildless Demo</title>
+  </head>
+  <body>
+    <!-- Your app will go here! -->
+    <div id="app"></div>
+
+    <!-- This is the magic part -->
+    <script type="module">
+      // 1. Import what you need from a CDN
+      import { createApp, useSignal, createMarkup } from "https://esm.sh/@manyducks.co/dolla";
+      import htm from "https://esm.sh/htm";
+
+      // 2. Tell HTM to use Dolla's markup function
+      const html = htm.bind(createMarkup);
+
+      // 3. Write your component using the `html` tag
+      function App() {
+        const [$count, setCount] = useSignal(0);
+
+        return html`
+          <div>
+            <h1>Count: ${$count}</h1>
+            <button onClick=${() => setCount((c) => c + 1)}>Click Me!</button>
+          </div>
+        `;
+      }
+
+      // 4. Mount your app into the #app element
+      createApp(App).mount("#app");
+    </script>
+  </body>
+</html>
+```
+
+Just save that file and open it in your browser. That's it. You have a fully reactive Dolla app running. No terminal, no `npm install`.
+
+## How it Works: The `html` Tag
+
+Let's break down the key part. This line:
+
+```js
+const html = htm.bind(createMarkup);
+```
+
+...is the secret sauce. It creates a special "tag" for your template literals. Whenever you write `html\`...\``, HTM intercepts it and, instead of making a normal string, it uses Dolla's `createMarkup\` function to turn it into the same Markup Nodes that JSX would create.
+
+So, this JSX:
+
+```jsx
+<div class="greeting">Hello, {$name}</div>
+```
+
+Becomes this with HTM:
+
+```js
+html`<div class="greeting">Hello, ${$name}</div>`;
+```
+
+It's basically the same thing, just with a slightly different syntax. You use `${...}` to embed any JavaScript expression, whether it's a signal, a string, or an event handler.
+
+## A More Complex Example
+
+Let's see how our usual `Counter` example looks with HTM. It's almost identical.
+
+```html
+<script type="module">
+  import { createApp, useSignal, useEffect, Show, createMarkup } from "https://esm.sh/@manyducks.co/dolla";
+  import htm from "https://esm.sh/htm";
+
+  const html = htm.bind(createMarkup);
+
+  function Counter() {
+    const [$count, setCount] = useSignal(0);
+
+    useEffect(() => {
+      console.log("The count is now:", $count());
+    });
+
+    return html`
+      <div>
+        <p>Count: ${$count}</p>
+        <button onClick=${() => setCount((c) => c + 1)}>+1</button>
+
+        {/* You can even use other components inside! */}
+        <${Show} when=${() => $count() > 5}>
+          <p>It's over 5!</p>
+        <//>
+      </div>
+    `;
+  }
+
+  createApp(Counter).mount("#app");
+</script>
+```
+
+The only weird part is using other components. You have to use the `${...}` syntax for the component itself, like `<${Show} ...>`. It's a little quirky, but you get used to it.
+
+## So, Why Bother?
+
+Going buildless is the main character for a few situations:
+
+- **Quick Prototypes & Demos:** You can spin up a reactive demo in seconds. Perfect for CodePen, Glitch, or just a file on your desktop.
+- **Learning:** It's a sick way to learn Dolla without getting bogged down in build tool configuration.
+- **Embedding in Existing Sites:** Got a simple static site and just want to add a little island of reactivity? This is perfect.
+
+For a huge, complex production app, you'll probably still want a build step with Vite for stuff like code splitting, bundling, and all that optimization. But for getting started or for smaller projects, going buildless is a total power move.
+
+---
+
+End.
+
+- [🗂️ Docs](./index.md)
+- [🏠 README](../README.md)
+- [🦆 That's a lot of ducks.](https://www.manyducks.co)