@fusion.dev/helix 0.0.0-dev

package/dist/app-header/root/app-header-root.d.ts

@@ -0,0 +1,103 @@
+import { HelixHeadlessAppHeader } from '@fusion.dev/helix-headless/app-header';
+import type { CSSResultGroup } from 'lit';
+/**
+ * @summary Page-level banner holding brand, navigation, and actions.
+ *
+ * @description
+ * Flat, opaque, and in the flow. Both of the interesting things a banner can do
+ * are opt-in: `sticky` because following the reader is a decision about the
+ * page rather than about the bar, and `appearance="material"` because a
+ * backdrop filter makes the header a containing block for `position: fixed`
+ * descendants, so an overlay rendered inside a material header is placed
+ * against the header rather than the viewport.
+ *
+ * The separating rule appears only once the page has scrolled, which keeps the
+ * banner flat against a hero and lifts it off the content afterwards. There is
+ * no shadow: the rule is the whole of it.
+ *
+ * @since 0.1.0
+ * @status stable
+ * @category navigation
+ * @aliases Masthead, Navbar, TopBar
+ * @documentation https://helix.fusion.dev/components/app-header
+ *
+ * @slot - Primary navigation.
+ * @slot actions - Trailing actions, such as a call to action.
+ * @slot brand - Wordmark or logo, at the inline start.
+ *
+ * @csspart content - The centered row inside the banner.
+ *
+ * @cssproperty --app-header-backdrop - The filter behind it. `none` to pair it with a panel.
+ * @cssproperty --app-header-background-color - Fill behind the banner.
+ * @cssproperty --app-header-block-size - Height of the banner.
+ * @cssproperty --app-header-border-color - The line under the bar. None by default.
+ * @cssproperty --app-header-max-inline-size - Width the content is centered in.
+ * @cssproperty --app-header-padding - Inline padding of the banner.
+ */
+export declare class HelixAppHeader extends HelixHeadlessAppHeader {
+    /**
+     * What the banner is made of, which is how much of what is behind it shows
+     * through.
+     *
+     * One axis, three points, and absent is opaque, per the rule that a reflected
+     * property takes no default.
+     *
+     * - Absent is opaque. The page stops at the bar, which is what an application
+     *   wants: the bar is chrome and chrome does not need to be interesting.
+     * - `glass` is translucent and blurred, so content passing underneath stays
+     *   visible and goes soft. The page reads as one surface with a bar floating
+     *   over it.
+     * - `transparent` has no fill at all until something has scrolled under it,
+     *   and then it takes the glass. For a banner over a hero, where the art
+     *   should reach the top of the window and the bar should only become a
+     *   surface once it has to be legible over moving content.
+     *
+     * **This was `appearance`, and it was filed under the wrong axis from the
+     * start.** The library's test is the one `Card` states: `separation` is where
+     * a surface ends, `tone` is what it means, `material` is what it is made of,
+     * and a property belongs to `material` when it can be true at the same time
+     * as the other two. Every value here varies exactly one quantity, and that
+     * quantity is translucency. The proof is inside the component rather than in
+     * the argument: scrolled, `transparent` emits the same two declarations
+     * `glass` does, so two of the three points are the same material arriving at
+     * different times.
+     *
+     * **One axis rather than two, and that is the whole reason it stays an
+     * enum.** The three are mutually exclusive: a bar cannot be opaque and
+     * see-through. Splitting the glass out and leaving `appearance="transparent"`
+     * beside it would make `material="glass" appearance="transparent"` sayable,
+     * which is a state with nothing to mean, where an enum makes it unsayable.
+     *
+     * The vocabulary got more coherent on the way. `flat` is a word about shape,
+     * `material` was a word about categories and `transparent` a word about
+     * light; opaque, glass and transparent are three points in one language.
+     *
+     * **`material` makes the header a containing block for `position: fixed`
+     * descendants**, which is worth knowing and is narrower than it sounds. Every
+     * overlay in this library goes into the top layer through the popover API or
+     * `<dialog>`, and the top layer is not laid out against its DOM ancestors:
+     * measured, a popover inside a blurred bar opens at the window origin while a
+     * plain `position: fixed` child of the same bar opens at the bar's. So a
+     * menu, a tooltip or a select in a material header is unaffected, and what is
+     * caught is a consumer's own hand-positioned element.
+     */
+    material?: 'frosted' | 'glass' | 'transparent';
+    /**
+     * Whether the banner sticks to the top of the viewport.
+     *
+     * Opt in, because following the reader is a decision about the page rather
+     * than about the bar, and because a reflected `true` writes an attribute the
+     * server's markup does not have. Every default here is the absent attribute.
+     *
+     * It pairs with `material`: a bar that does not stick is only ever over the
+     * top of the page, so `glass` and `transparent` have nothing to be
+     * translucent against and the `scrolled` state never lands.
+     */
+    sticky: boolean;
+    static styles: CSSResultGroup;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-app-header': HelixAppHeader;
+    }
+}

package/dist/app-header/root/app-header-root.js

@@ -0,0 +1,72 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { customElement } from '@fusion.dev/helix-core';
+import { HelixHeadlessAppHeader } from '@fusion.dev/helix-headless/app-header';
+import { property } from 'lit/decorators.js';
+import { styles } from './app-header-root.css.js';
+/**
+ * @summary Page-level banner holding brand, navigation, and actions.
+ *
+ * @description
+ * Flat, opaque, and in the flow. Both of the interesting things a banner can do
+ * are opt-in: `sticky` because following the reader is a decision about the
+ * page rather than about the bar, and `appearance="material"` because a
+ * backdrop filter makes the header a containing block for `position: fixed`
+ * descendants, so an overlay rendered inside a material header is placed
+ * against the header rather than the viewport.
+ *
+ * The separating rule appears only once the page has scrolled, which keeps the
+ * banner flat against a hero and lifts it off the content afterwards. There is
+ * no shadow: the rule is the whole of it.
+ *
+ * @since 0.1.0
+ * @status stable
+ * @category navigation
+ * @aliases Masthead, Navbar, TopBar
+ * @documentation https://helix.fusion.dev/components/app-header
+ *
+ * @slot - Primary navigation.
+ * @slot actions - Trailing actions, such as a call to action.
+ * @slot brand - Wordmark or logo, at the inline start.
+ *
+ * @csspart content - The centered row inside the banner.
+ *
+ * @cssproperty --app-header-backdrop - The filter behind it. `none` to pair it with a panel.
+ * @cssproperty --app-header-background-color - Fill behind the banner.
+ * @cssproperty --app-header-block-size - Height of the banner.
+ * @cssproperty --app-header-border-color - The line under the bar. None by default.
+ * @cssproperty --app-header-max-inline-size - Width the content is centered in.
+ * @cssproperty --app-header-padding - Inline padding of the banner.
+ */
+let HelixAppHeader = class HelixAppHeader extends HelixHeadlessAppHeader {
+    constructor() {
+        super(...arguments);
+        /**
+         * Whether the banner sticks to the top of the viewport.
+         *
+         * Opt in, because following the reader is a decision about the page rather
+         * than about the bar, and because a reflected `true` writes an attribute the
+         * server's markup does not have. Every default here is the absent attribute.
+         *
+         * It pairs with `material`: a bar that does not stick is only ever over the
+         * top of the page, so `glass` and `transparent` have nothing to be
+         * translucent against and the `scrolled` state never lands.
+         */
+        this.sticky = false;
+    }
+    static { this.styles = styles; }
+};
+__decorate([
+    property({ reflect: true })
+], HelixAppHeader.prototype, "material", void 0);
+__decorate([
+    property({ reflect: true, type: Boolean })
+], HelixAppHeader.prototype, "sticky", void 0);
+HelixAppHeader = __decorate([
+    customElement('helix-app-header')
+], HelixAppHeader);
+export { HelixAppHeader };

package/dist/aura/index.d.ts

@@ -0,0 +1 @@
+export * from './root/aura-root.js';

package/dist/aura/index.js

@@ -0,0 +1 @@
+export * from './root/aura-root.js';

package/dist/aura/root/aura-axis.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Where the axis leaves the top edge, and the tilt that puts it there.
+ *
+ * **Two functions, and the pair is the point.** `exitOf` is a model of what the
+ * shader does; `tiltFor` is the solve a consumer's `terminus` goes through. One
+ * is the inverse of the other, so a spec can go round the loop and catch either
+ * one moving without the other. Nothing else can: `bearing` is private, its
+ * output is a uniform, and what that uniform does is a WebGL draw.
+ *
+ * That guard is the whole reason this file exists. `terminus` was wrong twice
+ * while its docstring said otherwise, out by a factor of two and by the aspect
+ * correction, so `0.5` exited at 81.3% of the width on the landing page's own
+ * box and `0` was the only value that reached the middle. Both times the
+ * arithmetic lived inside a getter, beside a sentence describing different
+ * arithmetic, and nothing compared them. See 155.
+ *
+ * **`exitOf` mirrors the shader step by step rather than stating the closed
+ * form**, which is deliberate and is what makes the round trip worth running.
+ * A closed form checked against its own algebra proves only that the algebra
+ * was inverted correctly. Written as the same three operations `main()`
+ * performs, in the same order, it is a claim about `aura-shader.ts`, and the
+ * day someone changes how that file handles the aspect this stops agreeing.
+ */
+/**
+ * Where the shader's axis crosses the top edge, as a fraction of the width.
+ *
+ * Follows `main()` in `aura-shader.ts`:
+ *
+ * 1. `p.x *= aspect` stretches the frame before anything rotates, so the tilt
+ *    the rotation takes is a slope in the stretched frame rather than on
+ *    screen.
+ * 2. `float a = atan(sin(want), cos(want) * aspect)` is the angle it actually
+ *    turns by, which is the asked-for screen angle converted into that frame.
+ * 3. `mat2 turn = mat2(cos(a), sin(a), -sin(a), cos(a))` rotates, and the axis
+ *    is the line the rotated x is zero on: `cos(a) * x - sin(a) * y = 0`.
+ *
+ * At the top edge `y` is 1, so the crossing is at `x = tan(a)` in the stretched
+ * frame, and dividing the stretch back out puts it on screen. The aspect is
+ * therefore paid twice, once going into the rotation and once coming out, which
+ * is why it appears squared when the three steps are collapsed.
+ *
+ * @param tilt - The angle handed to the shader, in degrees.
+ * @param aspect - The box's width over its height.
+ * @returns The crossing, `0` at the left edge and `1` at the right.
+ */
+export declare const exitOf: (tilt: number, aspect: number) => number;
+/**
+ * The tilt, in degrees, whose axis crosses the top edge at `terminus`.
+ *
+ * The inverse of `exitOf`, solved rather than fitted: collapsing its three
+ * steps gives `terminus = 0.5 + tan(tilt) / (2 * aspect^2)`, and rearranging
+ * for the tilt gives what is below.
+ *
+ * This is the contract `terminus` has always claimed and twice failed to keep:
+ * `0` is the left edge, `0.5` the middle and `1` the right edge, in every box.
+ *
+ * @param terminus - The crossing wanted, as a fraction of the width.
+ * @param aspect - The box's width over its height.
+ * @returns The tilt to hand the shader, in degrees.
+ */
+export declare const tiltFor: (terminus: number, aspect: number) => number;

package/dist/aura/root/aura-axis.js

@@ -0,0 +1,68 @@
+/**
+ * Where the axis leaves the top edge, and the tilt that puts it there.
+ *
+ * **Two functions, and the pair is the point.** `exitOf` is a model of what the
+ * shader does; `tiltFor` is the solve a consumer's `terminus` goes through. One
+ * is the inverse of the other, so a spec can go round the loop and catch either
+ * one moving without the other. Nothing else can: `bearing` is private, its
+ * output is a uniform, and what that uniform does is a WebGL draw.
+ *
+ * That guard is the whole reason this file exists. `terminus` was wrong twice
+ * while its docstring said otherwise, out by a factor of two and by the aspect
+ * correction, so `0.5` exited at 81.3% of the width on the landing page's own
+ * box and `0` was the only value that reached the middle. Both times the
+ * arithmetic lived inside a getter, beside a sentence describing different
+ * arithmetic, and nothing compared them. See 155.
+ *
+ * **`exitOf` mirrors the shader step by step rather than stating the closed
+ * form**, which is deliberate and is what makes the round trip worth running.
+ * A closed form checked against its own algebra proves only that the algebra
+ * was inverted correctly. Written as the same three operations `main()`
+ * performs, in the same order, it is a claim about `aura-shader.ts`, and the
+ * day someone changes how that file handles the aspect this stops agreeing.
+ */
+/** Degrees to radians, which both directions need. */
+const RADIANS = Math.PI / 180;
+/**
+ * Where the shader's axis crosses the top edge, as a fraction of the width.
+ *
+ * Follows `main()` in `aura-shader.ts`:
+ *
+ * 1. `p.x *= aspect` stretches the frame before anything rotates, so the tilt
+ *    the rotation takes is a slope in the stretched frame rather than on
+ *    screen.
+ * 2. `float a = atan(sin(want), cos(want) * aspect)` is the angle it actually
+ *    turns by, which is the asked-for screen angle converted into that frame.
+ * 3. `mat2 turn = mat2(cos(a), sin(a), -sin(a), cos(a))` rotates, and the axis
+ *    is the line the rotated x is zero on: `cos(a) * x - sin(a) * y = 0`.
+ *
+ * At the top edge `y` is 1, so the crossing is at `x = tan(a)` in the stretched
+ * frame, and dividing the stretch back out puts it on screen. The aspect is
+ * therefore paid twice, once going into the rotation and once coming out, which
+ * is why it appears squared when the three steps are collapsed.
+ *
+ * @param tilt - The angle handed to the shader, in degrees.
+ * @param aspect - The box's width over its height.
+ * @returns The crossing, `0` at the left edge and `1` at the right.
+ */
+export const exitOf = (tilt, aspect) => {
+    const want = tilt * RADIANS;
+    const turned = Math.atan2(Math.sin(want), Math.cos(want) * aspect);
+    const stretched = Math.tan(turned);
+    return (stretched / aspect + 1) / 2;
+};
+/**
+ * The tilt, in degrees, whose axis crosses the top edge at `terminus`.
+ *
+ * The inverse of `exitOf`, solved rather than fitted: collapsing its three
+ * steps gives `terminus = 0.5 + tan(tilt) / (2 * aspect^2)`, and rearranging
+ * for the tilt gives what is below.
+ *
+ * This is the contract `terminus` has always claimed and twice failed to keep:
+ * `0` is the left edge, `0.5` the middle and `1` the right edge, in every box.
+ *
+ * @param terminus - The crossing wanted, as a fraction of the width.
+ * @param aspect - The box's width over its height.
+ * @returns The tilt to hand the shader, in degrees.
+ */
+export const tiltFor = (terminus, aspect) => Math.atan(2 * (terminus - 0.5) * aspect * aspect) / RADIANS;

package/dist/aura/root/aura-root.css.d.ts

@@ -0,0 +1 @@
+export declare const styles: import("lit").CSSResult;

package/dist/aura/root/aura-root.css.js

@@ -0,0 +1,35 @@
+// Generated from src/aura/root/aura-root.css by `bun run styles`. Do not edit.
+import { createSheet } from '@fusion.dev/helix-core';
+export const styles = createSheet(`:host {
+position: relative;
+display: block;
+inline-size: 100%;
+block-size: 100%;
+
+background-image: radial-gradient(
+120% 90% at 62% 12%,
+color-mix(in oklab, var(--helix-color-primary) 38%, var(--helix-color-background)) 0%,
+var(--helix-color-primary-subtle) 38%,
+var(--helix-color-background) 78%
+);
+}
+
+:host {
+pointer-events: none;
+}
+
+:host([interactive]) {
+pointer-events: auto;
+}
+
+[part="canvas"] {
+display: block;
+inline-size: 100%;
+block-size: 100%;
+}
+
+@media print {
+:host {
+display: none;
+}
+}`);