@rak200/ui 0.2.15 → 0.2.17

package/dist/placement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"placement.d.ts","sourceRoot":"","sources":["../src/placement.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,gGAAgG;AAChG,MAAM,MAAM,IAAI,GAAG,aAAa,GAAG,WAAW,CAAC;AAE/C,sEAAsE;AACtE,MAAM,MAAM,KAAK,GAAG,QAAQ,GAAG,cAAc,CAAC;AAE9C,6FAA6F;AAC7F,MAAM,WAAW,GAAG;IAChB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CAC3B;AAED,6EAA6E;AAC7E,MAAM,WAAW,SAAS;IACtB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAChC;AAOD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,KAAK,CACjB,MAAM,EAAE,GAAG,EACX,GAAG,EAAE,GAAG,EACR,QAAQ,EAAE;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAC7D,MAAM,EAAE,IAAI,EACZ,KAAK,EAAE,KAAK,GACb,SAAS,CAuBX"}

package/dist/placement.js

@@ -0,0 +1,60 @@
+/**
+ * Where an overlay lands, as arithmetic rather than as a rendering.
+ *
+ * **One answer to one problem, which is what issue #23 asked for.** `<ui-tooltip>` settled
+ * how this package places a `popover` — by hand, over the top layer, with CSS anchor
+ * positioning measured as present in this engine and deliberately declined; its docblock
+ * carries the whole argument. `<ui-menu>` needs the same thing pointing the other way, so
+ * the answer moved here rather than being written twice. A component with two placements is
+ * a component that is wrong in one of them.
+ *
+ * **Taken as numbers rather than as elements, and that is the floors talking** — the same
+ * reason `reservedGutter` in `src/dialog.ts` is handed two widths instead of a window. A
+ * function of four boxes is decided here and checked directly, at the edges that a rendered
+ * page can only reach by luck: an anchor with exactly the tip's height above it, a box wider
+ * than the viewport, a menu at the last pixel of the screen. The callers keep no branch of
+ * their own.
+ *
+ * Internal — not re-exported from `src/index.ts`, because what a consumer positions is their
+ * own element, and this is how two of ours find each other.
+ */
+/** The other one. A placement has two sides and flipping is what the second one is for. */
+function opposite(side) {
+    return side === 'block-start' ? 'block-end' : 'block-start';
+}
+/**
+ * Puts `box` beside `anchor` on the side it asked for, on the other side when there is no
+ * room, and inside the viewport either way.
+ *
+ * @param anchor - The element being pointed at, in viewport coordinates.
+ * @param box - The overlay, measured **after** it is shown: its height depends on how its
+ * text wrapped at this width in this font, which no caller can know and none should guess.
+ * @param viewport - The visible area, scrollbar excluded — `document.documentElement`'s
+ * client size rather than `window.inner*`, so a reserved scrollbar is not counted as room.
+ * @param prefer - Where it goes when it fits. A tip goes above its trigger; a menu hangs
+ * below its button.
+ * @param align - `center` for something that points at the anchor, `inline-start` for
+ * something that hangs from it.
+ */
+export function place(anchor, box, viewport, prefer, align) {
+    const room = prefer === 'block-start' ? anchor.top : viewport.height - (anchor.top + anchor.height);
+    const side = room >= box.height ? prefer : opposite(prefer);
+    // Looked up by name rather than compared against one, and that is a measurement rather
+    // than a style: `align === 'center' ? … : anchor.left` sends every OTHER name down the
+    // same arm, so the caller that passes `inline-start` could pass anything at all — an
+    // empty string included — and this would compute the same number. Keyed by the name,
+    // each one reaches its own value and no other name reaches either.
+    const lined = {
+        center: anchor.left + anchor.width / 2 - box.width / 2,
+        'inline-start': anchor.left,
+    }[align];
+    return {
+        side,
+        blockStart: side === 'block-start' ? anchor.top - box.height : anchor.top + anchor.height,
+        // Lined up first, then pulled back inside — in that order, because a box centred on
+        // an anchor near the edge is a box half off the screen. `Math.max` last, so a box
+        // wider than the viewport starts at the leading edge rather than at a negative one.
+        inlineStart: Math.max(0, Math.min(lined, viewport.width - box.width)),
+    };
+}
+//# sourceMappingURL=placement.js.map

package/dist/placement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"placement.js","sourceRoot":"","sources":["../src/placement.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAuBH,2FAA2F;AAC3F,SAAS,QAAQ,CAAC,IAAU;IACxB,OAAO,IAAI,KAAK,aAAa,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,aAAa,CAAC;AAChE,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,KAAK,CACjB,MAAW,EACX,GAAQ,EACR,QAA6D,EAC7D,MAAY,EACZ,KAAY;IAEZ,MAAM,IAAI,GACN,MAAM,KAAK,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,MAAM,CAAC,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;IAC3F,MAAM,IAAI,GAAG,IAAI,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAE5D,uFAAuF;IACvF,uFAAuF;IACvF,qFAAqF;IACrF,qFAAqF;IACrF,mEAAmE;IACnE,MAAM,KAAK,GAAG;QACV,MAAM,EAAE,MAAM,CAAC,IAAI,GAAG,MAAM,CAAC,KAAK,GAAG,CAAC,GAAG,GAAG,CAAC,KAAK,GAAG,CAAC;QACtD,cAAc,EAAE,MAAM,CAAC,IAAI;KAC9B,CAAC,KAAK,CAAC,CAAC;IAET,OAAO;QACH,IAAI;QACJ,UAAU,EAAE,IAAI,KAAK,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,GAAG,MAAM,CAAC,MAAM;QACzF,oFAAoF;QACpF,kFAAkF;QAClF,oFAAoF;QACpF,WAAW,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC;KACxE,CAAC;AACN,CAAC"}

package/dist/toast.d.ts

@@ -0,0 +1,158 @@
+import { LitElement, type TemplateResult } from 'lit';
+/** What a toast is telling the reader, which decides how it looks *and* how it is announced. */
+export type ToastVariant = 'info' | 'success' | 'warning' | 'danger';
+/**
+ * The live regions a toast is announced through, and the box the stack is drawn in.
+ *
+ * **One container, two regions, and the count is the number of politenesses rather than
+ * the number of messages.** A live region has to be in the document *before* the text is
+ * put into it — a region that arrives with its content already inside is the single most
+ * common way a toast is never announced — so the regions are rendered on connection and
+ * never removed, and a toast is added to whichever one its variant names.
+ *
+ * That is the whole reason there are two. `aria-live` cannot vary per message inside one
+ * region, and giving each toast its own `aria-live` would make every message its own
+ * region root, which is the shape this component exists to avoid. Two regions that outlive
+ * every message answer *politeness is per toast* without ever creating one.
+ *
+ * **Neither region carries `role="alert"` or `role="status"`**, and that is not a shortcut.
+ * Both roles imply `aria-atomic="true"`, so every arrival re-announces the whole stack —
+ * three toasts up means the third one reads all three. `aria-live` alone leaves
+ * `aria-atomic` at its `false` default, which announces the toast that arrived and nothing
+ * else. The semantics of `role="alert"` are `aria-live="assertive"` plus that atomicity;
+ * this keeps the half that is right for a stack.
+ *
+ * ## Where it sits
+ *
+ * A `popover`, for the reason `<ui-tooltip>` is one: the top layer escapes every stacking
+ * context and every `overflow: hidden` above it, so this package still names no `z-index`
+ * and opens no layering category — the third overlay in a row not to. `manual`, because an
+ * `auto` popover light-dismisses, and a toast that vanished on the next click somewhere
+ * else would be a notice the user never read.
+ *
+ * It is shown once, on connection, and never hidden — which costs the one thing promotion
+ * would have bought. A modal `<dialog>` opened *after* the toaster connects sits above it
+ * in the top layer, and re-promoting the stack per message would fix that ordering and
+ * break the announcement, by taking the region out of the tree and putting it back with
+ * content already in it. The trade is not close, and it is not the real limit anyway: a
+ * modal makes the rest of the document **inert**, so a toaster outside an open modal is out
+ * of the accessibility tree whichever layer it is in. `docs/toast.md` says where to put one
+ * for a page that toasts from inside a dialog.
+ *
+ * @example
+ * ```html
+ * <ui-toaster></ui-toaster>
+ * ```
+ */
+export declare class UiToaster extends LitElement {
+    static readonly styles: import("lit").CSSResult;
+    connectedCallback(): void;
+    render(): TemplateResult;
+}
+/**
+ * One message in a {@link UiToaster}.
+ *
+ * ## The variant decides three things, and that is the design
+ *
+ * `variant` is not only how the toast looks. It decides how urgently the message is
+ * announced and whether it expires, because those three answers are one answer: **an error
+ * is the message the reader has to see, hear, and keep.** So `danger` is announced
+ * assertively and never times out, and every other variant is polite and does.
+ *
+ * The alternative was a second attribute for politeness, and it was rejected for what it
+ * makes possible rather than for what it costs: two knobs can disagree, and a polite error
+ * or an assertive success is a defect nothing reports. The issue behind this component
+ * asked for `assertive` to be *reserved for errors* — a rule the API can hold is worth more
+ * than a rule the documentation states. What it gives up is stated in `docs/toast.md`:
+ * there is no way to write an assertive success.
+ *
+ * **The colour is redundant and must stay redundant.** WCAG 1.4.1 asks that colour never be
+ * the only carrier of information, and here it never is: the message says what happened and
+ * the edge agrees with it. That is also what makes the component correct under
+ * `forced-colors`, where the edge goes flat and nothing is lost.
+ *
+ * ## Dismissal
+ *
+ * Manual always, timed unless the toast is an error or `duration` is `0`. There is
+ * deliberately no way to remove the dismiss button: a toast that cannot be dismissed *and*
+ * does not expire is a permanent obstruction, and that combination is one attribute away in
+ * every kit that offers the knob.
+ *
+ * The timer stops while the pointer is over the toast or the focus is inside it, and starts
+ * again when both have left — a notice must not expire while it is being read, which is
+ * WCAG 2.2.1 aimed at the only time limit this component has.
+ *
+ * **A dismissed toast removes itself.** `ui-dismiss` is dispatched first, while the element
+ * is still in the tree so the event can reach a listener above it; a framework rendering a
+ * list of toasts drops the entry there rather than leaving the element to be put back.
+ *
+ * @example
+ * ```html
+ * <ui-toaster>
+ *   <ui-toast variant="success">Saved.</ui-toast>
+ * </ui-toaster>
+ * ```
+ */
+export declare class UiToast extends LitElement {
+    #private;
+    static readonly styles: import("lit").CSSResult;
+    static readonly properties: {
+        variant: {
+            type: StringConstructor;
+            reflect: boolean;
+        };
+        duration: {
+            type: NumberConstructor;
+        };
+        dismissLabel: {
+            type: StringConstructor;
+            attribute: string;
+        };
+    };
+    /**
+     * What this toast is telling the reader.
+     *
+     * Reflected, because it is what the stylesheet selects on — and because it is the
+     * attribute a host reads back to find out how the toast will behave.
+     *
+     * A plain field rather than the `accessor` keyword, for the reason `src/button.ts`
+     * states beside its own.
+     */
+    variant: ToastVariant;
+    /**
+     * How long the toast waits before dismissing itself, in milliseconds; `0` never.
+     *
+     * Ignored when the variant is `danger`, which never expires. Not a token, for the
+     * reason the default carries: every duration name collapses under reduced motion, and
+     * a dwell time that collapsed would take the notice away from the reader who asked for
+     * less movement.
+     */
+    duration: number;
+    /**
+     * The accessible name of the dismiss button.
+     *
+     * This package's one user-facing string, and an attribute precisely because it is one:
+     * a page that is not in English replaces it rather than forking the component. It names
+     * the button and never appears on screen, which is why there is no way to leave it
+     * empty — an unnamed control is the failure this default exists to prevent.
+     */
+    dismissLabel: string;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    willUpdate(): void;
+    render(): TemplateResult;
+    /**
+     * Runs the exit, announces it, and takes the toast off the page.
+     *
+     * Bound as a field so it can be handed to a listener and called as a method without
+     * either losing `this`.
+     */
+    readonly dismiss: () => void;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'ui-toaster': UiToaster;
+        'ui-toast': UiToast;
+    }
+}
+//# sourceMappingURL=toast.d.ts.map

package/dist/toast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toast.d.ts","sourceRoot":"","sources":["../src/toast.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAa,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AAGjE,gGAAgG;AAChG,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;AAqBrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,qBAAa,SAAU,SAAQ,UAAU;IACrC,gBAAyB,MAAM,0BAiD7B;IAEO,iBAAiB,IAAI,IAAI;IAazB,MAAM,IAAI,cAAc;CAMpC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,qBAAa,OAAQ,SAAQ,UAAU;;IACnC,gBAAyB,MAAM,0BAqH7B;IAEF,gBAAyB,UAAU;;;;;;;;;;;;MAIjC;IAEF;;;;;;;;OAQG;IACH,OAAO,EAAE,YAAY,CAAU;IAE/B;;;;;;;OAOG;IACH,QAAQ,SAAS;IAEjB;;;;;;;OAOG;IACH,YAAY,SAAa;IAoChB,iBAAiB,IAAI,IAAI;IAwBzB,oBAAoB,IAAI,IAAI;IAO5B,UAAU,IAAI,IAAI;IAQlB,MAAM,IAAI,cAAc;IAsBjC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,QAAO,IAAI,CAEzB;CA0DL;AAWD,OAAO,CAAC,MAAM,CAAC;IACX,UAAU,qBAAqB;QAC3B,YAAY,EAAE,SAAS,CAAC;QACxB,UAAU,EAAE,OAAO,CAAC;KACvB;CACJ"}