@expressive/dom 0.8.1 → 0.9.0

package/README.md

@@ -54,7 +54,7 @@ const unmount = render(
 
 `style` on a component automatically reaches its rendered host root, including through component, fragment, provider, portal, and collection boundaries. A fragment applies it to each host root. Forwarded style overrides the root's own, with the outermost caller winning. A component which reads its `style` prop while rendering owns placement, and nothing is forwarded. It receives a frozen object of the caller's inline declarations - spread, pluck or merge it freely; the caller's classes travel hidden with it. `className` applies to elements only.
 
-A component may register immutable maps with `style(Component, map)`. A `_name` entry is a rule, applied by a truthy `_name` attribute or a matching host tag and emitted as one class named after its source; nested inside a rule it opens a descendant scope. Component names never match - they do not survive minification. Bare keys are declarations, or macro calls where a macro owns the name, and those at the top of a map form a base rule applied to each of the component's host roots. Macros are defined only by `macro()` - within a map, call a plain function instead. `$name` is reserved. `_` attributes never reach the DOM, and `0` or `''` leaves a rule off. A map never reaches inside a child component; only the class chain inherits.
+A component may register immutable maps with `style(Component, map)`. A `_name` entry is a rule, applied by a truthy `_name` attribute or a matching host tag and emitted as one class named after its source; nested inside a rule it opens a descendant scope. Component names never match - they do not survive minification. Bare keys are declarations, or macro calls where a macro owns the name, and those at the top of a map form a base rule applied to each of the component's host roots. Macros are methods of a `Style` subclass, whose `use()` returns the `style` resolving them; a function inside a map is a value, not a definition. `$name` is reserved. `_` attributes never reach the DOM, and `0` or `''` leaves a rule off. A map never reaches inside a child component; only the class chain inherits.
 
 ```tsx
 function Button({ active }: { active: boolean }) {
@@ -67,7 +67,7 @@ style(Button, {
 });
 ```
 
-Global maps use `macro(map)` and can live in side-effect imports. Register macros and styles before the first relevant render. A key resolves at its topmost definition; a macro returning its own name falls to the next definition down, then through any `'*'` handler. Unhandled keys reach the host, which joins arrays and rejects functions and objects - units belong to a macro, never a guess.
+Register styles before the component's first render. A key resolves at its topmost definition, the subclass first; a macro returning its own name falls to the next definition down, then through any `'*'` method. Unhandled keys reach the host, which joins arrays and rejects functions and objects - units belong to a macro, never a guess.
 
 Inline style always beats classes; among classes, a caller's rule beats the callee's, and a rule carried through more component `style` props wins - independent of render order. `false`, `null`, and `undefined` omit an entry; `0` remains a macro argument.
 

package/dist/index.d.ts

@@ -5,28 +5,11 @@ import { Component, Context, Model } from "@expressive/mvc";
 //#region src/style/stylesheet.d.ts
 type Member = Extract<keyof CSSStyleDeclaration, string>;
 type Settable = { [K in Member]-?: CSSStyleDeclaration[K] extends Function ? never : K }[Member];
-type Key = style.Property | keyof macro$1.Registry | `--${string}` | `_${string}` | style.Condition;
-type Argument<K extends keyof macro$1.Registry> = macro$1.Registry[K] extends ((value: infer A, ...rest: any[]) => any) ? A : never;
-declare namespace macro$1 {
-  /**
-   * Macros visible to a style map. A pack augments this interface to declare
-   * what it registers with `macro()`.
-   */
-  interface Registry {}
-  /**
-   * Registry entries for the macros in a pack, so one line declares them all:
-   * `interface Registry extends macro.From<typeof pack> {}`.
-   */
-  type From<T> = { [K in keyof T as K extends `_${string}` | `$${string}` | '*' ? never : K]: T[K] };
-  /** Maps one argument to style, or to keys which resolve further. */
-  type Fn = (value: any, key: string) => unknown;
-  /**
-   * Body of a `macro()` map. A name declared in {@link Registry} must match its
-   * declaration; an undeclared one is accepted, and becomes checkable at call
-   * sites once a module augments `Registry` with it.
-   */
-  type Map = Partial<Registry> & { [K in `_${string}`]?: style.Map } & Record<string, Fn | style.Map | undefined>;
-}
+type Macro<T> = Extract<Exclude<{ [K in keyof T]-?: T[K] extends ((...args: any[]) => unknown) ? K : never }[keyof T], '*'>, string>;
+type Argument<F> = F extends ((...args: infer P) => any) ? P extends [] ? true : P[0] | (undefined extends P[0] ? true : never) : never;
+type Key<T> = style.Property | Macro<T> | `--${string}` | `_${string}` | style.Condition;
+type Layers<T> = readonly (style.Map<T> | Layers<T> | false | null | undefined)[] & { [K in style.Property | Macro<T>]?: unknown };
+type Body<T> = style.Map<T> | Layers<T>;
 declare namespace style {
   /** CSS property names, minus the CSSOM's own members. */
   type Property = Exclude<Settable, 'length' | 'parentRule' | 'cssText'>;
@@ -38,33 +21,40 @@ declare namespace style {
   /** What a declaration or macro argument may be; never a plain object. */
   type Value = string | number | boolean | null | undefined | readonly Value[];
   /**
-   * Body of a `style()` map. Bare keys are declarations or macro calls,
-   * `_name` opens a rule or descendant scope, `:state` and `@media …` apply
-   * their body conditionally, and `$name` is reserved.
+   * Body of a `style()` map. Bare keys are declarations or calls to a macro
+   * of `T`, `_name` opens a rule or descendant scope, `:state` and `@media …`
+   * apply their body conditionally, and `$name` is reserved. A rule or
+   * condition body may be an array of maps, merged in order.
    */
-  type Map = { [K in Key]?: K extends `_${string}` | Condition ? Map : K extends keyof macro$1.Registry ? Argument<K> | (undefined extends Argument<K> ? true : never) : Value };
+  type Map<T = {}> = { [K in Key<T>]?: K extends `_${string}` | Condition ? Body<T> : K extends Macro<T> ? Argument<T[K]> : Value };
+  /** A `style()` whose maps may call the macros of `T`. */
+  interface Apply<T> {
+    <C extends object>(type: C, ...maps: (Map<T> | false | null | undefined)[]): C;
+  }
+}
+/**
+ * Base class for a macro pack. Each method is a macro, layered over the class
+ * it extends; `'*'` handles any key no macro owns.
+ */
+declare class Style {
+  /** The `style()` for this pack, created once per class. */
+  static use<T extends Style>(this: new () => T): style.Apply<T>;
 }
 declare function style<T extends object>(type: T, ...maps: (style.Map | false | null | undefined)[]): T;
-declare function macro$1(rules: macro$1.Map): macro$1.Map;
 //#endregion
 //#region src/style/css.d.ts
 /**
- * Web macro pack. Register with `macro(css)` to opt into pixel units for
- * numbers and the `size` shorthand.
+ * Web macro pack - pixel units for numbers and the `size` shorthand. Extend
+ * it, or use it as is with `Css.use()`.
  */
-declare const css: {
-  '*': (value: unknown, key: string) => {
-    [x: string]: unknown;
+declare class Css extends Style {
+  '*'(value: unknown, key: string): {
+    [key]: unknown;
   };
-  size: (value: style.Value) => {
+  size(value: style.Value): {
     width: any;
     height: any;
   };
-};
-declare module '@expressive/dom' {
-  namespace macro {
-    interface Registry extends macro.From<typeof css> {}
-  }
 }
 //#endregion
 //#region src/style/units.d.ts
@@ -73,6 +63,7 @@ declare const em: (...values: number[]) => string;
 declare const px: (...values: number[]) => string;
 //#endregion
 //#region src/style/media.d.ts
+declare const order: readonly ["minWidth", "maxWidth", "minHeight", "maxHeight", "orientation", "hover", "pointer", "prefersColorScheme", "prefersReducedMotion"];
 interface Query {
   minWidth?: number | string;
   maxWidth?: number | string;
@@ -84,7 +75,13 @@ interface Query {
   prefersColorScheme?: 'light' | 'dark';
   prefersReducedMotion?: 'reduce' | 'no-preference';
 }
-declare function media(query: Query): `@media ${string}`;
+type Kebab<K extends string> = K extends `${infer A}${infer B}` ? A extends Uppercase<A> ? `-${Lowercase<A>}${Kebab<B>}` : `${A}${Kebab<B>}` : K;
+type Unit<V> = V extends number ? `${V}px` : V & string;
+type Features<Q, O extends readonly string[]> = O extends readonly [infer K extends string, ...infer R extends readonly string[]] ? K extends keyof Q ? Q[K] extends undefined ? Features<Q, R> : [`(${Kebab<K>}: ${Unit<Q[K]>})`, ...Features<Q, R>] : Features<Q, R> : [];
+type Join<T extends readonly string[]> = T extends readonly [infer H extends string, ...infer R extends readonly string[]] ? R extends [] ? H : `${H} and ${Join<R>}` : '';
+type Optional<Q> = { [K in keyof Q]-?: Q[K] extends undefined ? never : undefined extends Q[K] ? K : never }[keyof Q];
+type Media<Q extends Query> = [Optional<Q>] extends [never] ? `@media ${Join<Features<Q, typeof order>>}` : `@media ${string}`;
+declare function media<const Q extends Query>(query: Q): Media<Q>;
 //#endregion
 //#region src/render/fiber.d.ts
 type Container = Element | DocumentFragment;
@@ -92,5 +89,5 @@ type Container = Element | DocumentFragment;
 //#region src/render/render.d.ts
 declare function render(node: Node, container: Container): () => void;
 //#endregion
-export { Fragment, type JSX, Portal, createElement, css, em, macro$1 as macro, media, px, rem, render, style };
+export { Css, Fragment, type JSX, Portal, Style, createElement, em, media, px, rem, render, style };
 //# sourceMappingURL=index.d.ts.map