dothtml-interfaces 0.3.13 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dothtml-interfaces",
-  "version": "0.3.13",
+  "version": "0.4.0",
   "description": "Dependency injection interfaces for DOTHtml.",
   "main": "src/index.d.ts",
   "types": "src/index.d.ts",

package/src/{i-component.d.ts → i-dot-component.d.ts}

@@ -1,6 +1,5 @@
 
 import { IDotCore, IDotDocument } from "./i-dot";
-import IDotCss from "./styles/i-dot-css";
 
 // export type EventNames<T> = T extends { allowedEvents: infer E } ? E : never;
 
@@ -18,7 +17,7 @@ export interface FrameworkItems {
 		readonly shadowRoot: ShadowRoot;
 		readonly isRendered: boolean;
 		readonly tagName: string;
-		readonly styles: Array<string>;
+		// readonly styles: Array<string>; // Can't have this anymore because it's a memory leak.
 		readonly args: Array<any>;
 		// readonly styleElement: HTMLStyleElement;
 		readonly sharedStyles: CSSStyleSheet[];
@@ -31,7 +30,7 @@ export interface FrameworkItems {
 // TODO: there's a weird problem where if a constructor is not provided, it's not possible have a custom builder.
 // It should be the contsructor that depends on the builder, not the other way around. If we can't get this working, 
 // it might just be better to rethink how stuff gets passed into components.
-export default interface IComponent/*<TProps extends Array<string> = [], TEvents extends Array<string> = []>*/ {
+export default interface IDotComponent/*<TProps extends Array<string> = [], TEvents extends Array<string> = []>*/ {
 
 	readonly _?: FrameworkItems;
 
@@ -77,8 +76,9 @@ export default interface IComponent/*<TProps extends Array<string> = [], TEvents
 	 * A function that returns a string containing CSS rules to be applied to all instances of the component.
 	 * It will only be called exactly once per component. We use a function so that you can return a potentially 
 	 * large string containing CSS without introducing a memory leak. The reason it's not static is so that 
-	 * it will work in JavaScript, and because static members are not valid in DI interfaces.
-	 * @returns A string containing CSS rules.
+	 * it will work in JavaScript, and because static members are not valid in DI interfaces. All styles are scoped
+	 * to the component's shadow DOM.
+	 * @returns A string (or array of strings) containing imported CSS rules.
 	 */
-	stylize?(): string;
+	stylize?(): string|Array<string>;
 }

package/src/i-dot.d.ts

@@ -1,15 +1,15 @@
 
-import IComponent, { FrameworkItems } from "./i-component";
+import IDotComponent from "./i-dot-component";
 import IDotCss from "./styles/i-dot-css";
 import IEventBus from "./i-event-bus";
-import {IReactive} from "./i-reactive";
+import {IBoundReactive, IReactive} from "./i-reactive";
 import IDotcssProp from "./styles/i-css-prop";
 
 type DotContentPrimitive = string | number | boolean;
-type DotContentBasic = DotContentPrimitive | Node | Element | NodeList | IComponent | IDotDocument//typeof DotDocument;
-export type DotContent = DotContentBasic | Array<DotContent> | IReactive;//|(()=>DotContent);
+type DotContentBasic = DotContentPrimitive | Node | Element | NodeList | IDotComponent | IDotDocument//typeof DotDocument;
+export type DotContent = DotContentBasic | Array<DotContent> | IBoundReactive;//|(()=>DotContent);
 
-type AttrVal<T = string | number | boolean> = T | IReactive<T>;
+type AttrVal<T = string | number | boolean> = T | IBoundReactive<T>;
 
 /**
  * Global interface containing elements.
@@ -25,7 +25,7 @@ export interface IDotDocument {
 	/**
 	 * A conditional function, analogous to if. Renders the specified DOT if a condition is met. Dynamic binding is possible when condition and callback are functions.
 	*/
-	when(condition: IReactive | boolean, DotContent): IDotConditionalDocument;
+	when(condition: IBoundReactive | boolean, DotContent): IDotConditionalDocument;
 
 	// Main functions.
 	// TODO: please make this into a test case.
@@ -46,16 +46,16 @@ export interface IDotDocument {
 	/**
 	 * Creates a generic HTML node that can render a string, HTML nodes, or dotHTML content.
 	*/
-	html(content: string | number | boolean | IReactive): IDotDocument;
+	html(content: string | number | boolean | IBoundReactive): IDotDocument;
 	/**
 	 * Creates a text node that will render as a string, rather than being parsed as markup.
 	*/
-	text(content: string | number | boolean | IReactive): IDotDocument;
+	text(content: string | number | boolean | IBoundReactive): IDotDocument;
 	/**
 	 * Mounts a component.
 	 * TODO: add second arg.
 	 */
-	mount<T extends IComponent>(component: T): IDotDocument;
+	mount<T extends IDotComponent>(component: T): IDotDocument;
 	// mount<T extends IComponent>(init: (c: IMountedComponent<T>) => IMountedComponent<T> | void, component: T): IDotDocument;
 	// mount(component: IComponent, init: (init=>IMountedComponent): IMountedComponent|void): IDotDocument;
 	/**
@@ -65,7 +65,7 @@ export interface IDotDocument {
 	*/
 	iterate(n: number, callback: (i: number) => DotContent): IDotDocument;
 	each<T>(a: Array<T> | { [key: string | number]: T }, callback: (x: T, i: number, k: string | number) => DotContent): IDotDocument;
-	each<T>(a: IReactive<any, Array<T> | { [key: string | number]: T }>, callback: (x: T, i: IReactive<number>, k: string | number) => DotContent): IDotDocument;
+	each<T>(a: IBoundReactive<any, Array<T> | { [key: string | number]: T }>, callback: (x: T, i: IBoundReactive<number>, k: string | number) => DotContent): IDotDocument;
 
 	/**
 	 * Removes the targeted document and everything in it.
@@ -372,7 +372,7 @@ export interface IDotCore extends IDotDocument {
 	bus: IEventBus;
 	window: IDotWindowBuilder;
 
-	watch<Ti = IReactive | Array<any> | { [key: string | number]: any } | string | number | boolean, To = Ti>(initValue?: Ti, props?: { key?: string, transformer?: (value: Ti) => To }): IReactive<Ti, To>;
+	watch<Ti = IBoundReactive | Array<any> | { [key: string | number]: any } | string | number | boolean>(initValue?: Ti, key?: (Ti extends Array<any> | { [key: string | number]: any } ? string : never)): IReactive<Ti>;
 
 	// Keep these around for a bit to show how it was done before in case I need to change anything prior to the v6 launch.
 	// component<T extends IComponent>(Base: new (...args: Parameters<T['build']>) => T): new (...args: Parameters<T['build']>) => T;
@@ -382,8 +382,8 @@ export interface IDotCore extends IDotDocument {
 	// Works but doesn't infer types from the component.
 	// There's room for improvement here but it's not clear to me how to do it.
 	// What I'd like to do is have the types tied to the IComponent interface rather than the component factory function.
-	component<TProps extends string[] = [], TEvents extends string[] = []>(Base: new () => IComponent, styles?: string|IDotcssProp|Array<string|IDotcssProp>)
-		: new (attrs?: ComponentArgs<TProps, TEvents>) => IComponent & { new (attrs?: ComponentArgs<TProps, TEvents>): IComponent };
+	component<TProps extends string[] = [], TEvents extends string[] = []>(Base: new () => IDotComponent, styles?: string|IDotcssProp|Array<string|IDotcssProp>)
+		: new (attrs?: ComponentArgs<TProps, TEvents>) => IDotComponent & { new (attrs?: ComponentArgs<TProps, TEvents>): IDotComponent };
 
 	useStyles(document: Document, styles: Styles): HTMLStyleElement;
 }
@@ -399,7 +399,7 @@ export interface IDotWindowWrapper{
 }
 
 export interface IDotWindowBuilder {
-	(options: {content: IDotDocument, width?: number, height?: number, title?: string}): IDotWindowWrapper;
+	(options: {content: IDotComponent|IDotDocument, width?: number, height?: number, title?: string}): IDotWindowWrapper;
 }
 
 export interface IDotConditionalDocument extends IDotDocument {
@@ -407,7 +407,7 @@ export interface IDotConditionalDocument extends IDotDocument {
 	 * A conditional catch, analogous to else if. Can be used after a when function. Evaluates if the previous when's condition was false.
 	 * Renders the specified DOT if a condition is met. Dynamic binding is possible when condition and callback are functions.
 	*/
-	otherwiseWhen(condition: IReactive | boolean, callback: DotContent): IDotConditionalDocument;
+	otherwiseWhen(condition: IBoundReactive | boolean, callback: DotContent): IDotConditionalDocument;
 	/**
 	 * A conditional final catch, analogous to else. Can be used after a when or otherwiseWhen function. Evaluates if the previous when/otherwiseWhen evaluated to false.
 	 * Renders the specified DOT if a condition is met. Dynamic binding is possible when callback is a function.
@@ -432,7 +432,7 @@ export interface IDotGlobalAttrs {
 	// TODO: this needs to be redone now. 
 	// The better way might be using the new reactive system instead of references.
 	// For now I'll leave it like this:
-	ref?: IReactive<HTMLElement>;
+	// ref?: IReactive<HTMLElement>;
 
 	/** @deprecated Deprecated in HTML5. Use CSS. */
 	bgColor?: AttrVal<unknown>;
@@ -995,7 +995,7 @@ interface IDotTrack extends IDotGlobalAttrs {
 
 interface IDotVideo extends IDotGlobalAttrs {
 	autoPlay?: AttrVal<boolean>;
-	buffered?: IReactive<unknown>; // Managed by browser not user. TODO: we can possibly use events to update observable objects.
+	buffered?: IBoundReactive<unknown>; // Managed by browser not user. TODO: we can possibly use events to update observable objects.
 	controls?: AttrVal<boolean>;
 	crossOrigin?: AttrVal<"anonymous"> | AttrVal<"use-credentials">;
 	height?: AttrVal<number>;

package/src/i-reactive.d.ts

@@ -1,25 +1,34 @@
 
-export interface IReactive<Ti = any, To = Ti>{
+export interface IReactive<T = any> extends IBoundReactive<T, T>{
 	// The untransformed value.
-	_value: Ti;
+	_value: T;
 	// Get the value.
-	getValue(): To;
+	getValue(): T;
 	// Set the value.
-	setValue(v: Ti|null|undefined);
+	setValue(v: T|null|undefined);
 
 	// Key is used for observable array proxy bindings.
 	// If a key is provided, it's used to uniquely identify array elements.
 	// If a key is not provided, identification is done automatically by the framework by comparing object references.
 	key: string;
-	// Optional transformer that can transform the input.
-	transform?: (input: Ti)=>To;
 	// subscribeNode(node: Node): number;
 	// subscribeAttr(node: HTMLElement, attributeName: string): number;
-	subscribeCallback(callback: (value: To)=>void): number;
+	subscribeCallback(callback: (value: T)=>void): number;
 	detachBinding(id: number);
 	updateObservers(): void;
+
+	bindAs<Td = string>(transform: {
+		display?: (v: T)=>Td;
+		read?: (v: string)=>T;
+	}): IBoundReactive<T, Td>;
 }
 
 export interface IReactiveWatcher<T = any>{
 	observerUpdate(value: T, obsreverId: number): void;
+}
+
+export interface IBoundReactive<T = any, Td = T>{
+	_source: IReactive<T>;
+	_get: ()=>Td;
+	_set: (v: string)=>void;
 }

package/src/index.d.ts

@@ -6,7 +6,7 @@ export { default as IDotCss } from "./styles/i-dot-css";
 export * from "./styles/i-dot-css";
 
 
-export { default as IComponent, FrameworkItems } from "./i-component";
+export { default as IDotComponent, FrameworkItems } from "./i-dot-component";
 
-export { IReactive, IReactiveWatcher } from "./i-reactive";
+export { IReactive, IReactiveWatcher, IBoundReactive } from "./i-reactive";
 export { default as IEventBus } from "./i-event-bus";

package/src/styles/css-types.d.ts

@@ -1,11 +1,11 @@
-import { IReactive } from "../i-reactive";
+import { IBoundReactive } from "../i-reactive";
 
 // Global keyword values.
-export type GKV = IReactive<string>|"inherit"|"initial"|"unset"|"revert"|"revert-layer";
+export type GKV = IBoundReactive<string>|"inherit"|"initial"|"unset"|"revert"|"revert-layer";
 
 export type ComplexType = string;
 
-export type ValueOrReactive<T> = T|IReactive<T>;
+export type ValueOrReactive<T> = T|IBoundReactive<T>;
 
 // BASIC TYPES
 export type Str = `"${string|""}"`|`'${string|""}'`; // TODO: wherever str is required, we could just inject quotes...

package/src/styles/i-css-prop.d.ts

@@ -1,11 +1,11 @@
 
-import { IReactive } from "../i-reactive";
 import { GKV, ValueOrReactive } from "./css-types";
 import IFilterProp from "./complex-css-types/i-filter-prop";
 import IShadowProp from "./complex-css-types/i-shadow-prop";
 import ITransformationProp from "./complex-css-types/i-transformation-prop";
 import ColorProp from "./mapped-types/color-props";
 import LengthProp from "./mapped-types/length-prop";
+import { IBoundReactive } from "../i-reactive";
 
 type BackgroundPositionShorthand2D = string;
 type BackgroundRepeatValues2d = "no-repeat"|"repeat"|"space"|"round";
@@ -93,7 +93,7 @@ export default interface IDotcssProp extends
 
 	background?: GKV|string; // TODO: shorthand. Requires advanced typing.
 	backgroundAttachment?: GKV|"scroll"|"fixed"|"local"; // ✔️
-	backgroundBlendMode?: GKV|Array<IReactive<string>|"darken"|"luminocity"|"normal">; // ✔️
+	backgroundBlendMode?: GKV|Array<IBoundReactive<string>|"darken"|"luminocity"|"normal">; // ✔️
 	backgroundPosition?: GKV|BackgroundPositionShorthand2D;
 	backgroundRepeat?: GKV|BackgroundRepeatValues2d;
 	backgroundClip?: GKV|string;

package/src/styles/i-dot-css.d.ts

@@ -1,11 +1,4 @@
-// import {IReactive} from "../i-reactive";
-// import { GKV, Color, ComplexType, Percentage } from "./css-types";
-// import IDotcssProp from "./i-css-prop";
-// import IFilterProp from "./i-filter-prop";
-// import IShadowProp from "./i-shadow-prop";
-// import { ITransformationProp } from "./i-transformation-prop";
-// import ColorProp from "./mapped-types/color-props";
-// import LengthProp from "./mapped-types/length-prop";
+
 
 import IAtColorProfileBuilder from "./at-rules/i-at-color-profile-builder";
 import IAtCounterStyleBuilder from "./at-rules/i-at-counter-style-builder";

package/src/styles/mapped-types/angle-prop.d.ts

@@ -1,6 +1,6 @@
-import { IReactive } from "../../i-reactive";
+import { IBoundReactive } from "../../i-reactive";
 
-type V = IReactive<any> | number | string;
+type V = IBoundReactive<any> | number | string;
 
 type AngleUnitSuffix = "" | "Deg" | "Grad" | "Rad" | "Turn";
 

package/src/styles/mapped-types/color-props.d.ts

@@ -1,6 +1,6 @@
-import { IReactive } from "../../i-reactive";
+import { IBoundReactive } from "../../i-reactive";
 
-type V = IReactive<number|string> | number | string;
+type V = IBoundReactive<number|string> | number | string;
 
 type ColorUnitSuffix = "" 
 	| "Rgb" 
@@ -20,7 +20,7 @@ type SpecialColors = "currentcolor"|"transparent";
 
 type ColorProp<Prefix extends string> = {
 	[Key in ColorUnitSuffix as `${Prefix}${Key}`]?: (
-		(Key extends "" ? IReactive<string> | NamedColor | SystemColor | SpecialColors | `#${string}` | `${"rgb"|"rgba"|"hsl"|"hsla"|"hwb"|"lab"|"lch"|"oklab"|"oklch"|"color"}(${string})` : void) |
+		(Key extends "" ? IBoundReactive<string> | NamedColor | SystemColor | SpecialColors | `#${string}` | `${"rgb"|"rgba"|"hsl"|"hsla"|"hwb"|"lab"|"lch"|"oklab"|"oklch"|"color"}(${string})` : void) |
 		(Key extends "Rgb" | "Hsl" | "HslDeg" | "HslGrad" | "HslRad" | "HslTurn" | "Hwb" | "HwbDeg" | "HwbGrad" | "HwbRad" | "HwbTurn" | "Lab" | "Lch" | "LchDeg" | "LchGrad" | "LchRad" | "LchTurn" | "Oklch" | "OklchDeg" | "OklchGrad" | "OklchRad" | "OklchTurn" ? [V, V, V] | [V, V, V, V] : void) |
 		(Key extends "Srgb" | "SrgbLinear" | "DisplayP3" | "A98Rgb" | "ProphotoRgb" | "Rec2020" | "Xyz" | "XyzD50" | "XyzD65" ? [V, V, V] : void)
 	);

package/src/styles/mapped-types/length-prop.d.ts

@@ -1,12 +1,12 @@
-import { IReactive } from "../../i-reactive";
+import { IBoundReactive } from "../../i-reactive";
 import { GKV } from "../css-types";
 // import { NumericLength } from "./css-types";
 
 type LengthUnitSuffix = "" | "Cm" | "Ch" | "Em" | "Ex" | "In" | "Mm" | "P" | "Pc" | "Pt" | "Px" | "Rem" | "Vh" | "Vw" | "VMax" | "VMin";
 
-type V<S> = IReactive<any> | number | S;
+type V<S> = IBoundReactive<any> | number | S;
 
-type LengthProp<Prefix extends string, Qty extends 1|2|3|4 = 1, S extends string|IReactive<any> = GKV> = {
+type LengthProp<Prefix extends string, Qty extends 1|2|3|4 = 1, S extends string|IBoundReactive<any> = GKV> = {
 	[Key in LengthUnitSuffix as `${Prefix}${Key}`]?: (
 		(Qty extends 1 ? V<S>|[V<S>] : void) |
 		(Qty extends 2 ? [V<S>, V<S>] : void) |