@fusion.dev/helix-headless 0.0.0-dev

package/dist/divider/root/divider-root.js

@@ -0,0 +1,116 @@
+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, HelixElement, slotFilled } from '@fusion.dev/helix-core';
+import { html, nothing } from 'lit';
+import { property } from 'lit/decorators.js';
+/**
+ * @summary Separates content into groups with a rule.
+ *
+ * @description
+ * The separator role lives on the rule inside the shadow root rather than on
+ * the host. A role does not need to cross the shadow boundary the way an IDREF
+ * does, and putting it on the rendered element means the semantics are in the
+ * server's markup with no attribute written during a lifecycle the server never
+ * runs.
+ *
+ * Use `orientation="vertical"` between items on one line, such as inside a
+ * toolbar. A vertical divider stretches to its flex parent rather than setting
+ * a height of its own.
+ *
+ * @since 0.1.0
+ * @status stable
+ * @category layout
+ * @aliases Separator, Rule
+ * @documentation https://helix.fusion.dev/components/divider
+ *
+ * @slot - Content set into the rule, such as the word between two sections.
+ *
+ * @csspart content - What is set into it.
+ * @csspart line - The rule itself, or each half of it where something is set in.
+ */
+let HelixHeadlessDivider = class HelixHeadlessDivider extends HelixElement {
+    constructor() {
+        super(...arguments);
+        /**
+         * Whether the rule is announced as a separator.
+         *
+         * Off by default, and out of the accessibility tree. Most rules on a page
+         * separate nothing: they underline a heading or close a section that space
+         * had already closed, and announcing every one as a separator is noise a
+         * screen-reader user has to walk past.
+         *
+         * An opt-in, not a `decorative` opt-out, because a boolean attribute cannot
+         * be turned off: `decorative="false"` parses as `true`, which would put the
+         * quiet default out of reach from HTML and leave it settable only as a
+         * property. An opt-in is absent by default, which every reflected property
+         * here has to be.
+         */
+        this.announced = false;
+    }
+    /**
+     * Marks the middle region when nothing has been set into it.
+     *
+     * A divider with no content has to be one continuous line, and the space
+     * either side of the content is what would break it. `:empty` cannot answer
+     * this and neither can `:host(:has(...))`, which is invalid CSS dropped at
+     * parse time: `check:selectors` caught exactly that rule here, written in
+     * this file, by an author who had already read the note saying so.
+     *
+     * On the region inside the shadow root rather than on the host, because an
+     * attribute written onto the host is a change to markup the consumer rendered.
+     */
+    markEmpty() {
+        const region = this.renderRoot?.querySelector('[part="content"]');
+        const empty = !slotFilled(this.renderRoot?.querySelector('slot'));
+        region?.toggleAttribute('data-empty', empty);
+        /* `hidden` beside the mirror, because `data-empty` is a hook the styled
+           sheet reads and this tier has no sheet: an empty region left in the box
+           tree is a gap a consumer cannot close without knowing to look for it. The
+           styled rule stays, because that sheet sets `display` on this part and so
+           outranks the UA one. */
+        region?.toggleAttribute('hidden', empty);
+    }
+    updated(changed) {
+        super.updated(changed);
+        this.markEmpty();
+    }
+    render() {
+        /* Two rules and a slot between them, always.
+         *
+         * `role="presentation"` is the honest default; `announced` is for the rule
+         * that genuinely divides one thing from another rather than just drawing a
+         * line under it.
+         *
+         * **Both halves are always rendered and the semantics stay on the first.**
+         * A rule with nothing set into it is one line with a zero-width slot and a
+         * second line of no length, which costs a reader nothing and costs the
+         * component the branch that would otherwise decide between two markups. It
+         * also means a consumer who slots something in later gets it without the
+         * element re-rendering into a different shape.
+         *
+         * The role is not repeated on the second half. Two separators where a reader
+         * crossed one line is the announcement saying twice what happened once, and
+         * the content between them is not a boundary of its own. */
+        return html `<div
+      part="line"
+      role=${this.announced ? 'separator' : 'presentation'}
+      aria-orientation=${this.announced ? (this.orientation ?? 'horizontal') : nothing}
+    ></div>
+      <span part="content"><slot @slotchange=${() => this.markEmpty()}></slot></span>
+      <div part="line" role="presentation"></div>`;
+    }
+};
+__decorate([
+    property({ reflect: true })
+], HelixHeadlessDivider.prototype, "orientation", void 0);
+__decorate([
+    property({ reflect: true, type: Boolean })
+], HelixHeadlessDivider.prototype, "announced", void 0);
+HelixHeadlessDivider = __decorate([
+    customElement('helix-headless-divider')
+], HelixHeadlessDivider);
+export { HelixHeadlessDivider };

package/dist/donut-chart/index.d.ts

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

package/dist/donut-chart/index.js

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

package/dist/donut-chart/root/donut-chart-root.d.ts

@@ -0,0 +1,209 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { nothing, type TemplateResult } from 'lit';
+import '../../tooltip/index.js';
+declare const HelixHeadlessDonutChart_base: typeof HelixElement & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinChartSourceInterface);
+/**
+ * @summary Parts of a whole as a ring, read from a table.
+ *
+ * @description
+ * The chart with the narrowest honest use, so the component is narrow too.
+ *
+ * **It reads one column and treats the rows as the parts.** Every other chart
+ * here takes a column per series; a ring has one whole to divide, and a second
+ * ring inside the first is two charts sharing a picture in the most literal
+ * way. So the first column of numbers is the series and each row is a slice.
+ *
+ * **It refuses negative values rather than drawing them.** A share of a whole
+ * cannot be less than nothing, and an arc for a negative number either runs
+ * backwards over its neighbours or is silently dropped. Those rows are skipped
+ * and the total is of what is left, which is the only reading that stays true.
+ *
+ * **The shape is drawn with a dashed stroke, not with arc commands.** One
+ * `<circle>` per slice, its dash set to the slice's share of the circumference
+ * and its offset to where the slice begins. Arc paths need the sweep flag and a
+ * large-arc flag, both of which flip at values a reader never sees coming, and
+ * a slice of exactly one whole becomes a path with no length at all.
+ *
+ * **And it keeps its aspect ratio**, alone among the charts here. The others
+ * set `preserveAspectRatio="none"` so one drawing fills any box and rescue
+ * their strokes with `vector-effect`; that rescues strokes and not geometry, so
+ * a ring drawn the same way is an ellipse in anything but a square.
+ *
+ * The table is the accessible representation and this drawing is `aria-hidden`.
+ *
+ * The properties below are written by this component and read by whoever draws
+ * it. A consumer sets none of them: they carry a number this element computed
+ * and CSS cannot, which is what lets a stylesheet on this tier draw the thing
+ * without measuring anything itself.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @category charts
+ * @aliases Pie Chart, Ring Chart, Share Chart
+ * @documentation https://helix.fusion.dev/components/donut-chart
+ *
+ * @slot - Goes in the middle of the ring. A total, usually.
+ *
+ * @csspart center - The middle of the ring, holding whatever is slotted.
+ * @csspart mark - The invisible point the tooltip is anchored to.
+ * @csspart plot - The drawing.
+ * @csspart segment - One slice.
+ * @csspart segment-edge - One slice as a closed shape, for a boundary to trace.
+ * @csspart tooltip - The bubble, forwarded from `Tooltip`.
+ * @csspart tooltip-anchor - The `Tooltip` element itself.
+ * @csspart tooltip-cell - One column's name and value inside the tooltip.
+ * @csspart tooltip-label - The slice's own name inside the tooltip.
+ * @csspart tooltip-name - A column's name inside the tooltip.
+ * @csspart tooltip-value - A column's value inside the tooltip.
+ * @csspart track - The ring the slices are drawn on.
+ *
+ * @cssproperty --donut-chart-stroke - How thick the ring is drawn, derived from `hole`.
+ */
+export declare class HelixHeadlessDonutChart extends HelixHeadlessDonutChart_base {
+    /**
+     * The pointer is not mapped across this one.
+     *
+     * Every other chart lays its readings out left to right, so the nearest is
+     * arithmetic on x. A ring's slices are real elements at every angle, and x
+     * alone would answer with whichever slice shared a horizontal position with
+     * the pointer: at three o'clock and at nine o'clock it would give the same
+     * reading for opposite sides of the chart. So the slices say which one they
+     * are and this only holds the answer.
+     *
+     * Set here rather than in a constructor, and that is not a style choice. The
+     * analyzer reads `this.pointer.axis = 'none'` in a constructor body as a
+     * declaration of a public field called `axis`, and failed the build with
+     * `HelixHeadlessDonutChart.tracks has no description` for a member that does not
+     * exist on this class at all.
+     */
+    connectedCallback(): void;
+    /**
+     * How much is left open in the middle.
+     *
+     * Absent is a ring with room for a total in it. `small` and `large` move the
+     * hole without moving the outer edge, so a chart keeps its footprint.
+     *
+     * **`none` is a pie**, and it is the same drawing rather than another one:
+     * the radius follows the thickness, so the inner edge reaching the center is
+     * what closing the hole means. A pie reads less accurately than a ring, angle
+     * being harder to judge than length, but it is not *misleading* the way a bar
+     * measured from anything but zero is, which is why this is a value here and
+     * the bar chart's baseline is not a property at all.
+     *
+     * **Geometry rather than a CSS hook, and it had to move.** This was
+     * `--donut-chart-thickness`, and the dash arithmetic needs the circumference,
+     * which needs the radius: reading a custom property means `getComputedStyle`,
+     * which is client-only, so a server would have drawn a different ring than
+     * the client. A plot's proportions are markup for the same reason `curve` is.
+     */
+    hole?: 'large' | 'none' | 'small';
+    /**
+     * How much of the circle the whole occupies.
+     *
+     * Absent is the full turn. `half` is a semi-donut: the same shares spread
+     * over a half circle that opens downward, which is the shape a dashboard
+     * uses when the ring sits above a figure and the space below it is doing
+     * something else.
+     *
+     * **A second property rather than another `hole` value**, because the two are
+     * different axes and can both be true: `hole` is radial and says how thick
+     * the band is, this is angular and says how far round it goes. A `half`
+     * `none` is a semi-pie and is a real thing to want.
+     *
+     * **Not a gauge**, and the distinction is worth stating because this row was
+     * first filed as one. A gauge is one value against a range, which is a
+     * different data shape entirely and is `Meter`, whose `round` example already
+     * draws the reading as a ring. This divides a whole into parts and then
+     * declines to use the bottom half of the circle.
+     *
+     * Reflected, because the stylesheet has three things to say about it: the
+     * rotation that puts the first slice at nine o'clock, the aspect ratio of a
+     * box that is no longer square, and where the middle sits once the bottom of
+     * the circle is not drawn.
+     */
+    sweep?: 'half';
+    /** The fraction of the circle the shares are spread over. */
+    private get span();
+    /** How thick the ring is drawn, in the drawing's own units. */
+    private get thickness();
+    /** The ring's radius, which follows its thickness so the outer edge holds. */
+    private get radius();
+    private get shares();
+    protected render(): TemplateResult;
+    /**
+     * The ring itself, behind a seam the styled tier can move.
+     *
+     * `aria-hidden`, because the table it was read from is the readable version
+     * and a screen reader hearing both hears the same numbers twice.
+     */
+    protected renderPlot(shares: {
+        fraction: number;
+        start: number;
+    }[]): TemplateResult;
+    /**
+     * The view box, cropped to what is actually drawn.
+     *
+     * A full turn uses the square. A half arc uses the band from the top of the
+     * ring down to the center line, plus the half stroke its flat ends hang
+     * below that, and cropping to it is the difference between a semi-donut and a
+     * semi-donut with an empty quarter of the box under it. The outer edge is
+     * `EDGE` from the center whatever the thickness, which is what makes this two
+     * numbers rather than a measurement.
+     */
+    private get frame();
+    /** One slice, as a dash the length of its share. */
+    protected renderSegment(share: {
+        fraction: number;
+        start: number;
+    }, index: number): TemplateResult;
+    /**
+     * The same slice again, as a shape with an inside.
+     *
+     * **A stroked arc has no boundary to draw, which is why this exists.** The
+     * segment above is a dash on a circle: the mark *is* the edge, so there is
+     * nothing for an outline to trace and nothing within it to fade. Anything
+     * wanting those two separately needs the slice as a closed path, and this is
+     * it: the outer arc, a step inward, the inner arc back, closed.
+     *
+     * **Rendered always and painted only sometimes**, which is what keeps this on
+     * this tier. Whether a boundary is drawn is a styled question and the answer
+     * lives in a stylesheet; whether the geometry a boundary would need exists at
+     * all is structural, and a component cannot conjure a shape from CSS. So the
+     * path is here for every donut and is `fill: none; stroke: none` until
+     * something asks for it.
+     *
+     * **Not a replacement for the dash, which was the first plan.** The dash
+     * carries three jobs and only one of them is the shape: a share growing is a
+     * `stroke-dasharray` interpolating with no reflow, and `@starting-style` on
+     * that same property is the whole reason the ring sweeps in rather than
+     * appearing. A `d` cannot do either. CSS interpolates one only between paths
+     * of identical command structure, and the large-arc flag flips the moment a
+     * slice crosses a half turn, so a growing slice would pop partway through the
+     * transition it was meant to smooth. Both animations stay on the dash and this
+     * path follows it.
+     *
+     * The turn to twelve o'clock is arithmetic here rather than the rotation the
+     * stylesheet gives the circles. That rule uses `transform-box: fill-box`, so
+     * it spins each element about its own bounding box, which is the ring's center
+     * for a circle and is not for a sector.
+     */
+    protected renderEdge(share: {
+        fraction: number;
+        start: number;
+    }, index: number): TemplateResult;
+    /**
+     * What a pointer resting on a slice shows.
+     *
+     * Placed in the middle rather than along an axis, a ring having none, and the
+     * middle is where a reader is already looking: the hole usually holds a
+     * total, so a tooltip over it replaces one figure with the one being asked
+     * about rather than covering something else.
+     */
+    protected renderTooltip(): TemplateResult | typeof nothing;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-donut-chart': HelixHeadlessDonutChart;
+    }
+}
+export {};