@caqophony/ui 0.4.0 → 0.5.0

package/dist/material.d.mts

@@ -37,7 +37,7 @@ interface BandProps {
     pad?: 'none' | 'tight' | 'section' | 'open';
     /** The previous band's `Vignette placement="hang"` hangs over this one's top edge. */
     under?: 'none' | 'overhang';
-    /** This band's clouds sit over the seam, so bands meet as layers, not a ruled line. They rise into the band above's bottom padding, up to 108px (58px on a phone). */
+    /** This band's clouds sit over the seam, so bands meet as layers, not a ruled line. They rise up to 108px (58px on a phone) into the band above, and a band of `pad` `none` or `tight` keeps clear of them. */
     edge?: BandEdgeSpec;
     /** Layered behind the content, clipped to the band, hidden from assistive tech. */
     backdrop?: ReactNode;
@@ -74,6 +74,48 @@ interface FigureProps {
 /** An image slot that records the spec of the bitmap that will replace it. */
 declare function Figure({ spec, alt, children, fit }: FigureProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * #5985 — the stacked subject zone's shape, width over height: 5:4. The
+ * design-tree catalog reads it from this export (by its literal type), so
+ * `check-tree`'s `stack-frame-ratio` and the author's prompt state the shape
+ * the zone is drawn in. The zone's class is `aspect-[5/4]`: a class cannot be
+ * interpolated, and a CSS variable set inline is one the class gate cannot see
+ * declared, so a browser test (`material-primitives-5956`) holds the drawn
+ * zone to this number, as `HEIGHT`'s `4rem` is held to the header.
+ */
+declare const STACK_ZONE_RATIO = 1.25;
+/**
+ * #5985 — the stacked zone's width at the narrowest view a page is judged at
+ * (390px): the zone is full width with no gutter. `check-tree`'s
+ * `art-text-min-size` scales a `stack` frame's text by it; a browser test holds
+ * it to the zone as drawn.
+ */
+declare const STACK_ZONE_MIN_WIDTH = 390;
+interface HeroSceneProps {
+    /**
+     * The hero's height from `lg` up, and both are minimums: taller copy grows it.
+     * `fold`: the first screen, below the header, up to 56rem. `tall`: 46rem.
+     */
+    height: 'fold' | 'tall';
+    /**
+     * The picture: a `Figure fit="fill"`. Its zone is a 5:4 box
+     * (`STACK_ZONE_RATIO`) in the stacked layout, and a column taller than wide, about 3:5 to 3:4, from `lg` up, so a
+     * piece of art draws a wide `only: "stack"` frame and a tall `only: "side"`
+     * frame, both `fit: "contain"`.
+     */
+    subject: ReactNode;
+    /**
+     * Which column holds the copy from `lg` up. Absent: `start`. #5985 round 2:
+     * the subject's fields read it, so a horizon piece in a side frame ends at the
+     * frame's edge toward the copy and runs on only away from it, and downward.
+     */
+    copySide?: 'start' | 'end';
+    /** The copy: its headline, its lede and its calls to action. */
+    children: ReactNode;
+}
+/** A hero with a stated height, its copy and its subject in zones of their own. */
+declare function HeroScene({ height, subject, copySide, children, }: HeroSceneProps): react_jsx_runtime.JSX.Element;
+
 declare const GAP: {
     readonly 1: "gap-1";
     readonly 2: "gap-2";
@@ -126,8 +168,7 @@ interface SplitProps {
 /** Text beside media; stacks on a phone with the text first. */
 declare function Split({ ratio, reverse, gap, children }: SplitProps): react_jsx_runtime.JSX.Element;
 interface SpacerProps {
-    /** `phone-sky`: room for the backdrop's picture on a phone, nothing from `md` up. */
-    size: 'hero' | 'section' | 'phone-sky';
+    size: 'hero' | 'section';
 }
 /** Empty rhythm between two things that are not in one `Stack`. */
 declare function Spacer({ size }: SpacerProps): react_jsx_runtime.JSX.Element;
@@ -143,13 +184,34 @@ interface SkyFieldProps {
     height: number;
     /** Which part stays in view when the box's shape differs. */
     anchor: 'top' | 'center' | 'bottom' | 'right';
-    /** Show only on a phone or only from `md` up. */
-    only?: 'phone' | 'desktop';
-    ground: Tone;
+    /** `cover` fills the box and may cut the field; `contain` keeps all of it. Absent: `cover`. */
+    fit?: 'cover' | 'contain';
+    /** Show on one side of a cut only: `phone`/`desktop` at `md`, `stack`/`side` (a `HeroScene`'s subject) at `lg`. */
+    only?: 'phone' | 'desktop' | 'stack' | 'side';
+    /** `none`: no ground of its own, so a field can stand in a zone over the band's. */
+    ground: Tone | 'none';
     children: ReactNode;
 }
-/** A flat illustration field: an SVG that covers its box. */
-declare function SkyField({ width, height, anchor, only, ground, children, }: SkyFieldProps): react_jsx_runtime.JSX.Element;
+/** A field's size: the one writer is its `SkyField`. */
+interface FieldSize {
+    width: number;
+    height: number;
+}
+/**
+ * #5985 round 2 — which way a field's horizon pieces run on past it. On a
+ * `close` side a piece ends at the frame's edge with a natural end (a bank's
+ * last bump, a ridge's slope, down to the field's bottom); `down` runs every
+ * fill on below the field's bottom.
+ */
+interface FieldReach {
+    left: 'bleed' | 'close';
+    right: 'bleed' | 'close';
+    down: boolean;
+}
+/** A field outside a `HeroScene`, `Band`'s edge and the stored art: the bleed both ways, filled to the field's bottom. */
+declare const BLEED_BOTH_SIDES: FieldReach;
+/** A flat illustration field: an SVG in its box, as `fit` says. */
+declare function SkyField({ width, height, anchor, fit, only, ground, children, }: SkyFieldProps): react_jsx_runtime.JSX.Element;
 interface HaloProps {
     cx: number;
     cy: number;
@@ -162,46 +224,87 @@ interface HaloProps {
 /** Concentric stepped rings: a sun, or any glow, as flat print layers. */
 declare function Halo({ cx, cy, rings }: HaloProps): react_jsx_runtime.JSX.Element;
 interface CloudBankProps {
-    /** Field width and height. */
-    width: number;
-    height: number;
-    /** The bank's top line. */
+    /** The bank's top line, in field units: it fills from here to the field's bottom. */
     y: number;
-    /** Bump radius range: `min` at least 0.1, `max` no less than `min`, at most 2000 bumps. */
+    /** Bump radius range, in field units: `min` at least 0.1, `max` no less than `min`. */
     min: number;
     max: number;
-    /** How far the top line climbs from the left edge to the right. */
+    /** How far the top line climbs from the left edge to the right, in field units. */
     climb?: number;
     /** Bumps wander around `y` instead of drifting from it: a long bank stays on its line. */
     level?: boolean;
     seed: number;
     tone: Tone;
 }
-/** A scalloped cloud bank running edge to edge and filled to the field's bottom. */
-declare function CloudBank({ width, height, y, min, max, climb, level, seed, tone, }: CloudBankProps): react_jsx_runtime.JSX.Element;
+/**
+ * The one writer of a cloud bank's outline, for `CloudBank`, `Band`'s edge and
+ * the stored art's generator: paths of one tone, painted in this order.
+ *
+ *   1. the left bleed, `BLEED_WIDTHS` field-widths out, from a second stream
+ *      drawn leftward;
+ *   2. the right bleed, the frame's stream carried on as far past;
+ *   3. the frame's run, from `-max` to just past the right edge, filled to the
+ *      field's bottom: byte for byte the path drawn before the bleed (#5985).
+ *
+ * The frame's run is its own path, painted last, so under `cover` no pixel in
+ * view moves: one longer path rasterises its edges a shade differently at small
+ * scales. Each bleed reaches under the run by half a `max`, below a diagonal
+ * the run's bumps rise away from, so no seam shows where they meet under
+ * `contain`, and no start edge lands in a zone.
+ *
+ * #5985 round 2 — `reach` (a `HeroScene`'s field): `down` fills every path on
+ * `DOWN_SHARE` of a field-height below the field's bottom, and a `close` side
+ * has no bleed: the run ends with a last bump, a quarter ellipse from the run's
+ * top down to the frame's edge at the foot of that fill, at least a `max` wide,
+ * so it never stands as a straight edge.
+ */
+declare function cloudBankPaths(field: FieldSize, bank: Omit<CloudBankProps, 'tone'>, reach: FieldReach): readonly string[];
+/**
+ * A scalloped cloud bank across its field, filled to the field's bottom.
+ * `data-scene-piece` names a horizon piece for the rendered check that it spans
+ * its zone.
+ */
+declare function CloudBank({ tone, ...bank }: CloudBankProps): react_jsx_runtime.JSX.Element;
 interface RidgeProps {
-    width: number;
-    height: number;
+    /** The ridge's base line, in field units: it fills from here to the field's bottom. */
     y: number;
-    /** How high the ridge rolls above `y`. */
+    /** How high the ridge rolls above `y`, in field units. */
     rise: number;
     /** The number of swells across the field. */
     swells: number;
     seed: number;
     tone: Tone;
 }
-/** A smooth ridge line, filled to the field's bottom. */
-declare function Ridge({ width, height, y, rise, swells, seed, tone, }: RidgeProps): react_jsx_runtime.JSX.Element;
+/**
+ * The one writer of a ridge's outline. Swells `0..n-1` are the ones drawn
+ * before the bleed (#5985); the same stream carries on `BLEED_WIDTHS` widths to
+ * the right, and as many widths of swells from a second stream lead in from the
+ * left, ending on `y`. One path: no stored art draws a ridge, so there are no
+ * pixels from before to keep.
+ *
+ * #5985 round 2 — `down` fills on `DOWN_SHARE` of a field-height below the
+ * field's bottom; on a `close` side (a `HeroScene`'s field, toward its copy)
+ * there is no bleed: the swell at the edge slopes down to the frame's edge at
+ * the foot of that fill.
+ */
+declare function ridgePath(field: FieldSize, ridge: Omit<RidgeProps, 'tone'>, reach: FieldReach): string;
+/** A smooth ridge line across its field, filled to the field's bottom. */
+declare function Ridge({ tone, ...ridge }: RidgeProps): react_jsx_runtime.JSX.Element;
 interface StarsProps {
-    width: number;
-    /** The band they scatter in, from the top. */
-    height: number;
+    /** How far down from the field's top they scatter: a fraction of the field's height, above 0 and at most 1. */
+    depth: number;
     count: number;
     seed: number;
     tone: Tone;
 }
-/** A scatter of small dots. */
-declare function Stars({ width, height, count, seed, tone }: StarsProps): react_jsx_runtime.JSX.Element;
+/** The one writer of where stars fall: across the field's width, down to `depth` of its height. */
+declare function starDots(field: FieldSize, { depth, count, seed }: Omit<StarsProps, 'tone'>): {
+    cx: string;
+    cy: string;
+    r: string;
+}[];
+/** A scatter of small dots across the field. */
+declare function Stars({ tone, ...stars }: StarsProps): react_jsx_runtime.JSX.Element;
 interface RoutePoint {
     x: number;
     y: number;
@@ -220,8 +323,241 @@ interface RouteLineProps {
     /** The label size, in field units. */
     labelSize: number;
 }
-/** A dashed route through waypoints, each marked by its state. */
-declare function RouteLine({ points, tone, markTone, labelSize, }: RouteLineProps): react_jsx_runtime.JSX.Element;
+/**
+ * A dashed route through waypoints, each marked by its state. Its line and
+ * marks draw where it stands among the pieces; its labels draw in its field's
+ * top layer (`SkyField` draws each direct `RouteLine` child again there), so no
+ * piece paints over a word.
+ */
+declare function RouteLine({ points, tone, markTone, labelSize, }: RouteLineProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * #5985 round 2 — the unit and the range of every number a scene piece takes,
+ * written once. The pieces (`sky.tsx`) hold each number to its range at render,
+ * with an exact error; the design-tree catalog reads this table from its
+ * literal type, so the catalogue line the author reads states the unit and the
+ * range, and the check (`scene-range`) names a number past it before anything
+ * renders. A key `list.field` is a field of each entry of a list prop.
+ *
+ * A bound is a number, or a multiple of the field's own width or height: a
+ * halo's centre stays in its field whatever size the author draws it at.
+ * `Stars depth={0.6}` (gencheck-2 mise-b) was read as 0.6 field units and drew
+ * a line of dots: a number with no stated unit is a guess on both sides.
+ *
+ * Imports nothing, so the catalog reads it with no JSX.
+ *
+ * Authored by Caqophony
+ */
+/** A bound of a range: a number, or `times` the field's `of`. */
+type SceneBound = number | {
+    readonly of: 'width' | 'height';
+    readonly times: number;
+};
+interface SceneMeasure {
+    /** What one of the number is, as the author reads it. */
+    readonly unit: string;
+    /** A whole number only. */
+    readonly whole: boolean;
+    readonly min: SceneBound;
+    /** `min` itself is outside the range. */
+    readonly minOpen: boolean;
+    /** Inclusive; null: no upper bound. */
+    readonly max: SceneBound | null;
+}
+declare const SCENE_MEASURES: {
+    readonly SkyField: {
+        readonly width: {
+            readonly unit: "field units, the frame's own coordinates";
+            readonly whole: false;
+            readonly min: 0;
+            readonly minOpen: true;
+            readonly max: null;
+        };
+        readonly height: {
+            readonly unit: "field units, the frame's own coordinates";
+            readonly whole: false;
+            readonly min: 0;
+            readonly minOpen: true;
+            readonly max: null;
+        };
+    };
+    readonly Halo: {
+        readonly cx: {
+            readonly unit: "field units";
+            readonly whole: false;
+            readonly min: 0;
+            readonly minOpen: false;
+            readonly max: {
+                readonly of: "width";
+                readonly times: 1;
+            };
+        };
+        readonly cy: {
+            readonly unit: "field units";
+            readonly whole: false;
+            readonly min: 0;
+            readonly minOpen: false;
+            readonly max: {
+                readonly of: "height";
+                readonly times: 1;
+            };
+        };
+        readonly 'rings.r': {
+            readonly unit: "field units";
+            readonly whole: false;
+            readonly min: 0;
+            readonly minOpen: true;
+            readonly max: {
+                readonly of: "width";
+                readonly times: 1;
+            };
+        };
+    };
+    readonly CloudBank: {
+        readonly y: {
+            readonly unit: "field units";
+            readonly whole: false;
+            readonly min: 0;
+            readonly minOpen: false;
+            readonly max: {
+                readonly of: "height";
+                readonly times: 1;
+            };
+        };
+        /** Below 0.1 a radius rounds to 0.0 in the path's one decimal. */
+        readonly min: {
+            readonly unit: "field units";
+            readonly whole: false;
+            readonly min: 0.1;
+            readonly minOpen: false;
+            readonly max: {
+                readonly of: "height";
+                readonly times: 1;
+            };
+        };
+        readonly max: {
+            readonly unit: "field units";
+            readonly whole: false;
+            readonly min: 0.1;
+            readonly minOpen: false;
+            readonly max: {
+                readonly of: "height";
+                readonly times: 1;
+            };
+        };
+        readonly climb: {
+            readonly unit: "field units";
+            readonly whole: false;
+            readonly min: {
+                readonly of: "height";
+                readonly times: -1;
+            };
+            readonly minOpen: false;
+            readonly max: {
+                readonly of: "height";
+                readonly times: 1;
+            };
+        };
+        readonly seed: {
+            readonly unit: "a seed: the same one draws the same shape";
+            readonly whole: true;
+            readonly min: 0;
+            readonly minOpen: false;
+            readonly max: 2147483646;
+        };
+    };
+    readonly Ridge: {
+        readonly y: {
+            readonly unit: "field units";
+            readonly whole: false;
+            readonly min: 0;
+            readonly minOpen: false;
+            readonly max: {
+                readonly of: "height";
+                readonly times: 1;
+            };
+        };
+        readonly rise: {
+            readonly unit: "field units";
+            readonly whole: false;
+            readonly min: 0;
+            readonly minOpen: false;
+            readonly max: {
+                readonly of: "height";
+                readonly times: 1;
+            };
+        };
+        readonly swells: {
+            readonly unit: "swells across the field";
+            readonly whole: true;
+            readonly min: 1;
+            readonly minOpen: false;
+            readonly max: 512;
+        };
+        readonly seed: {
+            readonly unit: "a seed: the same one draws the same shape";
+            readonly whole: true;
+            readonly min: 0;
+            readonly minOpen: false;
+            readonly max: 2147483646;
+        };
+    };
+    readonly Stars: {
+        readonly depth: {
+            readonly unit: "a fraction of the field's height";
+            readonly whole: false;
+            readonly min: 0;
+            readonly minOpen: true;
+            readonly max: 1;
+        };
+        readonly count: {
+            readonly unit: "stars";
+            readonly whole: true;
+            readonly min: 0;
+            readonly minOpen: false;
+            readonly max: 5000;
+        };
+        readonly seed: {
+            readonly unit: "a seed: the same one draws the same shape";
+            readonly whole: true;
+            readonly min: 0;
+            readonly minOpen: false;
+            readonly max: 2147483646;
+        };
+    };
+    readonly RouteLine: {
+        readonly 'points.x': {
+            readonly unit: "field units";
+            readonly whole: false;
+            readonly min: 0;
+            readonly minOpen: false;
+            readonly max: {
+                readonly of: "width";
+                readonly times: 1;
+            };
+        };
+        readonly 'points.y': {
+            readonly unit: "field units";
+            readonly whole: false;
+            readonly min: 0;
+            readonly minOpen: false;
+            readonly max: {
+                readonly of: "height";
+                readonly times: 1;
+            };
+        };
+        readonly labelSize: {
+            readonly unit: "field units";
+            readonly whole: false;
+            readonly min: 0;
+            readonly minOpen: true;
+            readonly max: {
+                readonly of: "height";
+                readonly times: 1;
+            };
+        };
+    };
+};
 
 interface DisplayProps {
     /** The scale step; `poster` is the page's one largest moment. */
@@ -276,4 +612,4 @@ interface WordmarkProps {
 /** A product name with its mark. */
 declare function Wordmark({ name, mark, href }: WordmarkProps): react_jsx_runtime.JSX.Element;
 
-export { Band, type BandEdgeSpec, type BandProps, CloudBank, type CloudBankProps, Columns, type ColumnsProps, Display, type DisplayProps, Figure, type FigureProps, type FigureSpec, type Gap, Halo, type HaloProps, Inline, type InlineProps, Inset, type InsetProps, Ridge, type RidgeProps, RouteLine, type RouteLineProps, type RoutePoint, SkyField, type SkyFieldProps, Spacer, type SpacerProps, Split, type SplitProps, Stack, type StackProps, Stars, type StarsProps, Text, type TextProps, type Tone, Vignette, type VignetteProps, Wordmark, type WordmarkProps };
+export { BLEED_BOTH_SIDES, Band, type BandEdgeSpec, type BandProps, CloudBank, type CloudBankProps, Columns, type ColumnsProps, Display, type DisplayProps, type FieldReach, type FieldSize, Figure, type FigureProps, type FigureSpec, type Gap, Halo, type HaloProps, HeroScene, type HeroSceneProps, Inline, type InlineProps, Inset, type InsetProps, Ridge, type RidgeProps, RouteLine, type RouteLineProps, type RoutePoint, SCENE_MEASURES, STACK_ZONE_MIN_WIDTH, STACK_ZONE_RATIO, type SceneBound, type SceneMeasure, SkyField, type SkyFieldProps, Spacer, type SpacerProps, Split, type SplitProps, Stack, type StackProps, Stars, type StarsProps, Text, type TextProps, type Tone, Vignette, type VignetteProps, Wordmark, type WordmarkProps, cloudBankPaths, ridgePath, starDots };