@manyducks.co/dolla 2.0.0-alpha.5 → 2.0.0-alpha.50

package/dist/translate/index.d.ts

@@ -0,0 +1,133 @@
+import type { Dolla } from "../core/dolla.js";
+import { type MaybeSignal, type Signal } from "../core/signals-api.js";
+/**
+ * A JSON object of translated strings. Values can be string templates or nested objects.
+ */
+interface LocalizedStrings extends Record<string, string | LocalizedStrings> {
+}
+/**
+ * A formatter to be applied to a variable.
+ */
+type Format = {
+    name: string;
+    options: Record<string, any>;
+};
+export interface TranslationConfig {
+    /**
+     * Name of the locale this translation is for (BCP 47 locale names recommended).
+     */
+    locale: string;
+    /**
+     * An object with translated strings for this language.
+     */
+    strings?: LocalizedStrings;
+    /**
+     * A callback function that returns a Promise that resolves to the translation object for this language.
+     */
+    fetch?: () => Promise<LocalizedStrings>;
+    /**
+     * Path to a JSON file with translated strings for this language.
+     */
+    path?: string;
+}
+export type I18nSetupOptions = {
+    /**
+     * Default locale to load on startup
+     */
+    locale?: string | null;
+    translations: TranslationConfig[];
+};
+export type TOptions = {
+    /**
+     *
+     */
+    count?: MaybeSignal<number>;
+    /**
+     *
+     */
+    context?: MaybeSignal<string>;
+    /**
+     * Override formats specified in the template with the ones in the array for each named variable.
+     *
+     * @example
+     * t("example_key", {
+     *   count: 5,
+     *   formatOverrides: {
+     *     count: [ { name: "datetime", options: { style: "currency", currency: "JPY" } } ]
+     *   }
+     * });
+     */
+    formatOverrides?: MaybeSignal<Record<string, Record<string, Format[]>>>;
+    [value: string]: MaybeSignal<any>;
+};
+export type Formatter = (locale: string, value: unknown, options: Record<string, any>) => string;
+/**
+ * Dolla's I(nternationalizatio)n module. Manages language translations and locale-based formatting.
+ */
+export declare class I18n {
+    #private;
+    readonly locale: Signal<string>;
+    constructor(dolla: Dolla);
+    get locales(): string[];
+    setup(options: I18nSetupOptions): void;
+    setLocale(name: string): Promise<void>;
+    /**
+     * Returns a State containing the value at `key`.
+  
+     * @param selector - Key to the translated value.
+     * @param options - A map of `{{placeholder}}` names and the values to replace them with.
+     *
+     * @example
+     * const $value = t("your.key.here", { count: 5 });
+     */
+    t(selector: string, options?: TOptions): Signal<string>;
+    /**
+     * Add a custom format callback.
+     *
+     * @example
+     * Dolla.i18n.addFormat("uppercase", (locale, value, options) => {
+     *   return value.toUpperCase();
+     * });
+     *
+     * {
+     *   "greeting": "Hello, {{name|uppercase}}!"
+     * }
+     *
+     * t("greeting", {name: "world"}); // State<"Hello, WORLD!">
+     */
+    addFormat(name: string, callback: (locale: string, value: unknown, options: Record<string, any>) => string): void;
+    /**
+     * Creates an `Intl.Collator` configured for the current locale.
+     * NOTE: The locale is tracked if called within a signal tracking context.
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/Collator#options
+     */
+    collator(options?: Intl.CollatorOptions): Intl.Collator;
+    /**
+     * Formats a number for the current locale. Uses `Intl.NumberFormat` under the hood.
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#options
+     */
+    number(count: MaybeSignal<number | bigint>, options?: Intl.NumberFormatOptions): Signal<string>;
+    /**
+     * Formats a date for the current locale. Uses `Intl.DateTimeFormat` under the hood.
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#options
+     *
+     * @example
+     * const date = new Date();
+     * const $formatted = Dolla.i18n.dateTime(date, { dateFormat: "short" });
+     */
+    dateTime(date?: MaybeSignal<string | number | Date | undefined>, options?: Intl.DateTimeFormatOptions): Signal<string>;
+    /**
+     * Formats a list for the current locale. Uses `Intl.ListFormat` under the hood.
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#options
+     *
+     * @example
+     * const list = new Date();
+     * const $formatted = Dolla.i18n.list(list, {  });
+     */
+    list(list: MaybeSignal<Iterable<string>>, options?: Intl.ListFormatOptions): Signal<string>;
+}
+export {};

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,6 +1,6 @@
 import type * as CSS from "csstype";
-import { Ref, type Markup } from "./markup.js";
-import { SettableSignal, Signal } from "./signals.js";
+import type { Markup } from "./core/markup.js";
+import { Signal } from "./core/signals-api.js";
 /**
  * Represents everything that can be handled as a DOM node.
  * These are all the items considered valid to pass as children to any element.
@@ -10,7 +10,7 @@ export type Stringable = {
     toString(): string;
 };
 type MaybeSignal<T> = T | Signal<T> | Signal<T | undefined>;
-type OptionalProperty<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";
@@ -23,6 +23,18 @@ 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.
      */
@@ -30,7 +42,6 @@ export interface ElementProps {
     /**
      * 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.
@@ -1219,9 +1230,9 @@ export interface PropertiesOf<E extends HTMLElement> extends HTMLElementProps {
      */
     children?: any;
     /**
-     * A settable signal or callback that receives the DOM node when rendered.
+     * 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);
 }
 /**
  * The following elements are defined based on the WHATWG HTML spec:
@@ -3143,7 +3154,6 @@ interface HTMLInputElementProps extends PropertiesOf<HTMLInputElement> {
     step?: OptionalProperty<number>;
     type?: OptionalProperty<InputType>;
     value?: OptionalProperty<string>;
-    $$value?: SettableSignal<any>;
     width?: OptionalProperty<string | number> | OptionalProperty<string> | OptionalProperty<number>;
     title?: OptionalProperty<string>;
     /**

package/dist/utils.d.ts

@@ -1,5 +1,18 @@
 export declare const noOp: () => void;
-export declare function deepEqual(one: any, two: any): boolean;
+export declare function getUniqueId(): string;
+/**
+ * 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 +26,10 @@ 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;
+/**
+ * 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/http.md

@@ -0,0 +1,29 @@
+# HTTP Client
+
+> TODO: Write me.
+
+This page goes into detail on how to use the built in HTTP client.
+
+```js
+import { http } from "@manyducks.co/dolla";
+
+http.use(async (req, next) => {
+  // Apply auth header to all API routes.
+  if (req.url.pathname.startsWith("/api/")) {
+    req.headers.set("authorization", `Bearer ${localStorage.getItem("api-key")}`);
+  }
+
+  await next();
+});
+
+const res = await http.get("/api/some-api-route");
+res.body; // body is already parsed as JSON if server responded with JSON
+```
+
+---
+
+End.
+
+- [🗂️ Docs](./index.md)
+- [🏠 README](../README.md)
+- [🦆 That's a lot of ducks.](https://www.manyducks.co)

package/docs/i18n.md

@@ -0,0 +1,38 @@
+# Internationalization (i18n) Support
+
+```jsx
+import Dolla, { createState, t } from "@manyducks.co/dolla";
+
+function CounterView(props) {
+  const [$count, setCount] = createState(0);
+
+  const increment = () => {
+    setCount((count) => count + 1);
+  };
+
+  return (
+    <div>
+      <p>Clicks: {$count}</p>
+      <button onClick={increment}>{t("buttonLabel")}</button>
+    </div>
+  );
+});
+
+Dolla.i18n.setup({
+  locale: "en",
+  translations: [
+    { locale: "en", strings: { buttonLabel: "Click here to increment" } },
+    { locale: "ja", strings: { buttonLabel: "ここに押して増加する" } },
+  ],
+});
+
+Dolla.mount(document.body, CounterView);
+```
+
+---
+
+End.
+
+- [🗂️ Docs](./index.md)
+- [🏠 README](../README.md)
+- [🦆 That's a lot of ducks.](https://www.manyducks.co)

package/docs/index.md

@@ -0,0 +1,10 @@
+# Dolla Docs
+
+> Write table of contents (see files in this folder in the meantime)
+
+---
+
+End.
+
+- [🏠 README](../README.md)
+- [🦆 That's a lot of ducks.](https://www.manyducks.co)

package/docs/router.md

@@ -0,0 +1,80 @@
+# Router
+
+Dolla makes heavy use of client-side routing. You can define as many routes as you have views, and the URL
+will determine which one the app shows at any given time. By building an app around routes, lots of things one expects
+from a web app will just work; back and forward buttons, sharable URLs, bookmarks, etc.
+
+Routes are matched by highest specificity regardless of the order they were registered.
+This avoids some confusing situations that come up with order-based routers like that of `express`.
+On the other hand, order-based routers can support regular expressions as patterns which Dolla's router cannot.
+
+## Route Patterns
+
+Routes are defined with strings called patterns. A pattern defines the shape the URL path must match, with special
+placeholders for variables that appear within the route. Values matched by those placeholders are parsed out and exposed
+to your code (`router` store, `$params` readable). Below are some examples of patterns and how they work.
+
+- Static: `/this/is/static` has no params and will match only when the route is exactly `/this/is/static`.
+- Numeric params: `/users/{#id}/edit` has the named param `{#id}` which matches numbers only, such as `123` or `52`. The
+  resulting value will be parsed as a number.
+- Generic params: `/users/{name}` has the named param `{name}` which matches anything in that position in the path. The
+  resulting value will be a string.
+- Wildcard: `/users/*` will match anything beginning with `/users` and store everything after that in params
+  as `wildcard`. `*` is valid only at the end of a route.
+
+Now, here are some route examples in the context of an app:
+
+```js
+import Dolla, { createRouter } from "@manyducks.co/dolla";
+import { ThingIndex, ThingDetails, ThingEdit, ThingDelete } from "./views.js";
+
+const router = createRouter({
+  routes: [
+    {
+      // A `null` component with subroutes acts as a namespace for those subroutes.
+      // Passing a view instead of `null` results in subroutes being rendered inside that view wherever `ctx.outlet()` is called.
+      path: "/things",
+      view: null,
+      routes: [
+        { path: "/", view: ThingIndex }, // matches `/things`
+        { path: "/{#id}", view: ThingDetails }, // matches `/things/{#id}`
+        { path: "/{#id}/edit", view: ThingEdit }, // matches `/things/{#id}/edit`
+        { path: "/{#id}/delete", view: ThingDelete }, // matches `/things/{#id}/delete`
+      ],
+    },
+    // All routes that don't match anything else will redirect to `/things`
+    { path: "*", redirect: "/things" },
+  ],
+});
+
+// Mount the router in place of a view.
+Dolla.mount(document.body, router);
+```
+
+When the URL matches a pattern the corresponding view is displayed. If we visit `/people/john`,
+we will see the `PersonDetails` view and the params will be `{ name: "john" }`. Params can be
+accessed from anywhere in the app through `Dolla.router`.
+
+```js
+import Dolla from "@manyducks.co/dolla";
+
+// Info about the current route is exported as a set of Readables. Query params are also Writable through $$query:
+const { $path, $pattern, $params, $query } = router;
+
+router.back(); // Step back in the history to the previous route, if any.
+router.back(2); // Hit the back button twice.
+
+router.forward(); // Step forward in the history to the next route, if any.
+router.forward(4); // Hit the forward button 4 times.
+
+router.go("/things/152"); // Navigate to another path within the same app.
+router.go("https://www.example.com/another/site"); // Navigate to another domain entirely.
+```
+
+---
+
+End.
+
+- [🗂️ Docs](./index.md)
+- [🏠 README](../README.md)
+- [🦆 That's a lot of ducks.](https://www.manyducks.co)

package/docs/setup.md

@@ -0,0 +1,31 @@
+# Setting up Dolla
+
+## Installation
+
+Dolla is published on npm as `@manyducks.co/dolla`. You can install it in your project with the following command:
+
+```
+npm i @manyducks.co/dolla
+```
+
+## JSX
+
+If you want to use JSX in your app you can add the following options to your `tsconfig.json` or `jsconfig.json`. Modern build systems like [Vite](https://vite.dev) will pick these up automatically.
+
+```json
+{
+  "compilerOptions": {
+    // ... other options ...
+    "jsx": "react-jsx",
+    "jsxImportSource": "@manyducks.co/dolla"
+  }
+}
+```
+
+---
+
+End.
+
+- [🗂️ Docs](./index.md)
+- [🏠 README](../README.md)
+- [🦆 That's a lot of ducks.](https://www.manyducks.co)