@fusion.dev/helix-core 0.2.0 → 0.3.0

package/dist/mixins/mixin-controller-open/mixin-controller-open.js

@@ -7,63 +7,13 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { property } from 'lit/decorators.js';
 import { HelixBeforeCloseEvent, HelixBeforeOpenEvent } from '../../events/events.js';
 import { requestChange } from '../../utils/request-change/request-change.js';
-/**
- * Grafts open state onto a base class, and says so twice.
- *
- * `helix-before-open` and `helix-before-close` announce the change while it is
- * still a request, so `preventDefault()` refuses it and nothing moves. Native
- * `toggle` announces it afterwards, once the state has actually gone, carrying
- * `newState` and `oldState` the way the platform does on `<details>` and on a
- * popover. The first is how a consumer takes the decision; the second is what
- * they bind when they only want to know.
- *
- * `open` is a seed and a correction rather than a claim: the element applies
- * its own changes from wherever markup started it, and `defaultOpen` is what a
- * reset returns to.
- *
- * Records `:state(open)` whenever the element is open. Styled tiers select on
- * that rather than on `[open]`, which is absent until somebody writes it.
- */
 export const MixinControllerOpen = (Base) => {
-    // JSDoc is duplicated from MixinControllerOpenInterface deliberately. The interface is
-    // what TypeScript consumers see; this class is what the manifest analyzer
-    // reads when resolving inherited members into dependent packages.
     class OpenElement extends Base {
         constructor() {
             super(...arguments);
-            /**
-             * Initial open state for uncontrolled use, where nothing declared one.
-             */
             this.defaultOpen = false;
-            /**
-             * The state, whoever set it, and `undefined` until somebody has.
-             *
-             * Prefixed, and it has to be. These mixins compose onto one prototype
-             * chain, `Select` takes this one and `MixinControllerValue` together, and
-             * TypeScript's `private` is a compile-time fiction: two mixins with a field
-             * called `state` share one property on the instance, and the second one
-             * silently overwrites the first. Measured, as a select whose `value` came
-             * back holding its `open` boolean.
-             *
-             * One field and not two. Writing always applies, the way a native control
-             * does when a script assigns to it.
-             */
             this.openState = undefined;
         }
-        /**
-         * Whether the element is open.
-         *
-         * One property, not two, so `dialog.open` answers the question anyone
-         * asking it meant. Writing always applies; `<helix-dialog open>` is the
-         * same statement in markup.
-         *
-         * **Not reflected, and that is required rather than tidy.** Reflection
-         * writes the resolved state back as an attribute, so an element that opened
-         * itself would put `open` on its own host: cloned, serialized for
-         * hydration, or diffed by a framework, it comes back holding whatever the
-         * last reader did rather than what the author wrote. `:state(open)` carries
-         * the resolved state for stylesheets, which is what the mirror is for.
-         */
         get open() {
             return this.openState ?? this.defaultOpen;
         }
@@ -72,31 +22,10 @@ export const MixinControllerOpen = (Base) => {
             this.openState = next;
             this.requestUpdate('open', previous);
         }
-        /**
-         * Records the resolved state as the custom state `open`.
-         *
-         * **A custom state and never `data-open`.** An attribute mirror is in the
-         * DOM, so an `<helix-accordion-item default-open>` served without it gains
-         * it on upgrade, which is a hydration mismatch a React consumer reports.
-         * See `HelixElement.toggleState`, and see `Toast.Item` for the other answer
-         * to the same fault: inverting the hook so the write falls on the side that
-         * only happens after somebody acts. Inversion works where the resting state
-         * is the loud one and cannot help here, `checked` and `open` being true
-         * only because a consumer asked for them.
-         */
         willUpdate(changed) {
             super.willUpdate(changed);
             this.toggleState('open', this.open);
         }
-        /**
-         * Requests an open-state change, and reports whether it was applied.
-         *
-         * Announces before it acts, so `preventDefault()` on the `helix-before-open` or
-         * `helix-before-close` is a refusal and nothing moves. Nobody refusing means the
-         * element opens or closes itself, whether or not a consumer declared
-         * `open`: a declared property is a seed and a correction, and a consumer
-         * who wants the decision for themselves refuses it and assigns their own.
-         */
         requestOpen(next) {
             if (this.open === next) {
                 return true;
@@ -116,27 +45,6 @@ export const MixinControllerOpen = (Base) => {
             }
             return applied;
         }
-        /**
-         * Says the state moved, under the platform's own name and in its shape.
-         *
-         * **A native `toggle` from inside a shadow root reaches nobody**, because
-         * it neither bubbles nor composes, so the ten families showing a
-         * `popover="manual"` panel and the two rendering a real `<dialog>` announce
-         * nothing to a consumer. The disclosures have no native element to fire
-         * anything at all: `AccordionItem` and `TreeItem` are `aria-expanded` and
-         * `hidden` written by hand, which is `<details>`'s job done manually.
-         *
-         * **From here rather than from `PopoverController`.** The controller covers
-         * eleven families and the mixin covers sixteen, so announcing from both
-         * would announce twice on the ten they share. What `toggle` reports is the
-         * *state*, and the state is this mixin's; the controller is a way of
-         * putting a panel on the screen.
-         *
-         * **`newState` and `oldState`, because that is the platform's shape**, so a
-         * consumer arriving from `<details>` reads the same two words. Not
-         * cancelable: the before events are the request, and a second cancelable
-         * event for one transition is two answers to one question.
-         */
         announceToggle(open) {
             const event = new Event('toggle', { bubbles: false, cancelable: false, composed: false });
             Object.assign(event, {
@@ -145,7 +53,6 @@ export const MixinControllerOpen = (Base) => {
             });
             this.dispatchEvent(event);
         }
-        /** Requests the opposite of the current state. */
         toggleOpen() {
             return this.requestOpen(!this.open);
         }

package/dist/mixins/mixin-controller-value/mixin-controller-value.js

@@ -7,64 +7,14 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { property } from 'lit/decorators.js';
 import { HelixBeforeChangeEvent } from '../../events/events.js';
 import { requestChange } from '../../utils/request-change/request-change.js';
-/**
- * Grafts `value`, `defaultValue`, and the two callbacks that answer a form.
- *
- * **Derived on read, never seeded in a lifecycle hook.** `value` falls back to
- * `defaultValue`, so the server and the client agree without either running a
- * hook. Seeding in `connectedCallback` is the trap: SSR never calls it, so a
- * control with a `default-value` would serve empty and fill itself at
- * hydration, a flash for a reader and a mismatch for React.
- *
- * **What it does not own is reporting.** `setFormValue` stays with the
- * component, because what an empty value means is the component's business: a
- * text field submits its emptiness, since `""` is an answer and the field was
- * on the form, while a group with nothing chosen submits nothing at all.
- *
- * `Checkbox` deliberately does not take this. Its `value` is what it submits
- * *when it is on* rather than what it holds, so it is configuration rather than
- * state, and the state it does have is `checked`, which is
- * `MixinControllerChecked`'s.
- */
 export const MixinControllerValue = (Base) => {
-    // JSDoc is duplicated from the interface deliberately. The interface is what
-    // TypeScript consumers see; this class is what the manifest analyzer reads
-    // when resolving inherited members into dependent packages.
     class ValueElement extends Base {
         constructor() {
             super(...arguments);
-            /**
-             * The value the markup declared, which is where a reset returns to.
-             */
             this.defaultValue = '';
-            /**
-             * The state, whoever set it, and `undefined` until somebody has.
-             *
-             * One field and not two. Writing always applies, the way a native control
-             * does when a script assigns to it.
-             */
             this.valueState = undefined;
-            /**
-             * Whether a reader edits this continuously, which decides the native name.
-             *
-             * The request event is `helix-before-change` whatever the answer; this
-             * decides which native event announces the result, `input` while a reader
-             * is editing against `change` when they are done, which is the distinction
-             * the platform already draws.
-             *
-             * Discrete by default: only a control the reader edits continuously says
-             * otherwise.
-             */
             this.announcesInput = false;
         }
-        /**
-         * What the control holds now, and what its form submits.
-         *
-         * One property, not two, so `input.value` answers the question anyone
-         * asking it meant. Writing always applies; `<helix-input value="x">` is the
-         * same statement in markup, and `default-value` is how markup seeds a value
-         * a reset should return to.
-         */
         get value() {
             return this.valueState ?? this.defaultValue;
         }
@@ -73,35 +23,12 @@ export const MixinControllerValue = (Base) => {
             this.valueState = next;
             this.requestUpdate('value', previous);
         }
-        /**
-         * Announces the applied value under the platform's own name.
-         *
-         * **After `apply`, never before**, which is the whole reason this is
-         * separate from the request event: a native handler reads
-         * `event.target.value`, and it has to be the value that was just applied.
-         *
-         * **Both, for a discrete control, because that is what the platform does.**
-         * A native `<select>` sends `input` and then `change` from one choice: the
-         * value moved, and the reader is also done. A continuous control announces
-         * `input` here and relays `change` from its inner control when the reader
-         * is done, so the pair keeps the platform's timings rather than reporting a
-         * commit on every keystroke.
-         */
         announceNatively() {
             this.dispatchEvent(new Event('input', { bubbles: true, composed: true }));
             if (!this.announcesInput) {
                 this.dispatchEvent(new Event('change', { bubbles: true, composed: false }));
             }
         }
-        /**
-         * Requests a new value, and reports whether the request stood.
-         *
-         * Announces before it acts, so `preventDefault()` on the `helix-before-change` is
-         * a refusal and nothing moves. Nobody refusing means the control updates
-         * itself, whether or not a consumer declared `value`: a declared property
-         * is a seed and a correction, the way `<input value>` is, and a consumer
-         * who wants the change for themselves refuses it and assigns their own.
-         */
         requestValue(next) {
             if (this.value === next) {
                 return true;
@@ -121,25 +48,11 @@ export const MixinControllerValue = (Base) => {
             }
             return applied;
         }
-        /**
-         * Returns the control to the value its markup declared.
-         *
-         * Both halves are dropped, the consumer's and the control's, because a
-         * reset means the form is as it was served. Clearing only the internal one
-         * would leave a control that had been written to stuck at that value.
-         */
         formResetCallback() {
             const previous = this.value;
             this.valueState = undefined;
             this.requestUpdate('value', previous);
         }
-        /**
-         * Restores the value when the browser brings a form back.
-         *
-         * Falling back to `defaultValue` rather than to empty, because a restore
-         * with no state is a form the browser has nothing recorded for, which is
-         * the same situation as a fresh one.
-         */
         formStateRestoreCallback(state) {
             const previous = this.value;
             this.valueState = state ?? undefined;

package/dist/mixins/mixin-dismissible/mixin-dismissible.js

@@ -6,58 +6,20 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 };
 import { property } from 'lit/decorators.js';
 import { HelixDismissEvent } from '../../events/events.js';
-/**
- * Grafts `dismissible`, its label, and the event that says so.
- *
- * **The label reads the default slot, never `this.textContent`**, which is
- * every light-DOM descendant including the ones assigned elsewhere. On
- * `Announcement` and `Tag` the two are the same thing, because they have one
- * slot. On `Toast.Item` the second sweeps in the actions: a message reading
- * "Could not reach the server" with a `Retry` button announces itself as "Could
- * not reach the server Retry", and the consumer removing it from their list
- * gets that string to match on.
- *
- * **`dismissEvent()` is separate from `dismiss()` for the one that needs it.**
- * `Announcement` and `Tag` dispatch and are done: they own no state, so a
- * refusal is the whole of the consumer's answer. `Toast.Item` holds an `open`
- * and applies the change itself, so its event goes through `requestChange` with
- * an `apply` beside it. Giving it the event rather than the method lets it keep
- * the contract and skip the default.
- */
 export const MixinDismissible = (Base) => {
     class Dismissible extends Base {
         constructor() {
             super(...arguments);
-            /**
-             * Whether it offers a control to take it away.
-             */
             this.dismissible = false;
-            /**
-             * Accessible name for that control.
-             *
-             * `attribute` is spelled out because Lit lowercases a property name to
-             * derive one rather than dash-casing it, so this would otherwise be
-             * reachable only as `dismisslabel`, which nobody would guess and no linter
-             * would catch.
-             */
             this.dismissLabel = 'Dismiss';
         }
-        /**
-         * The event, built and not dispatched.
-         *
-         * Reading text is safe here: nothing calls this on a server, because the
-         * only things that do are a press and a timer.
-         */
         dismissEvent() {
-            /* Default slot only. A node assigned to a named slot belongs to another
-               region and is not what this surface is called. */
             const own = [...this.childNodes]
                 .filter((node) => !(node instanceof Element) || !node.slot)
                 .map((node) => node.textContent ?? '')
                 .join('');
             return new HelixDismissEvent({ label: own.trim() });
         }
-        /** Announces that it should go, and reports whether the request stood. */
         dismiss() {
             const event = this.dismissEvent();
             this.dispatchEvent(event);