@h-k-dev/angular-email-editor 0.0.6 → 0.0.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@h-k-dev/angular-email-editor",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "An email editor for Angular on ProseMirror — a visual composer and an HTML source editor over one schema that is the vocabulary of email HTML.",
   "license": "MIT",
   "author": "h-k-dev",
@@ -131,6 +131,10 @@
     "./suggestion-menu": {
       "types": "./types/h-k-dev-angular-email-editor-suggestion-menu.d.ts",
       "default": "./fesm2022/h-k-dev-angular-email-editor-suggestion-menu.mjs"
+    },
+    "./toggle-button-group": {
+      "types": "./types/h-k-dev-angular-email-editor-toggle-button-group.d.ts",
+      "default": "./fesm2022/h-k-dev-angular-email-editor-toggle-button-group.mjs"
     }
   },
   "sideEffects": false,

package/types/h-k-dev-angular-email-editor-toggle-button-group.d.ts

@@ -0,0 +1,172 @@
+import * as _angular_core from '@angular/core';
+import { InjectionToken, Signal } from '@angular/core';
+import { FormValueControl } from '@angular/forms/signals';
+
+/** What an item needs of the group it stands in — `hk-tgb` provides it, so
+    an item finds its group without importing it. */
+interface ToggleButtonGroupHost<T = unknown> {
+    readonly value: Signal<T>;
+    readonly disabled: Signal<boolean>;
+    readonly tabStop: Signal<ToggleButtonGroupItem<T> | undefined>;
+    select(value: T): void;
+}
+declare const TOGGLE_BUTTON_GROUP: InjectionToken<ToggleButtonGroupHost<unknown>>;
+/**
+ * What every choice of an `hk-tgb` is, whichever shape it wears — the
+ * group finds its items by this class. Use one of the shapes:
+ * `hkTgbIcon` (round) or `hkTgbText` (a pill).
+ *
+ * An item makes its element — a `<button>`, an `<a>`, anything — a `radio`
+ * that carries a `value` and is `aria-checked` while the group holds it.
+ * The element and its content stay the host's: a font icon, a `mat-icon`,
+ * an SVG, a word. A click picks it, and Space and Enter do too (the
+ * group's keys), so a `<div>` works as well as a button. A `<button>`
+ * without a `type` gets `type="button"`, so an item in a form never
+ * submits it. `aria-disabled` takes it out of the choices and the arrow
+ * keys' way — it stays in the track, so the others keep their places —
+ * and stops a disabled link from being followed.
+ */
+declare abstract class ToggleButtonGroupItem<T = unknown> {
+    /** What the group's value is while this item is picked. */
+    readonly value: _angular_core.InputSignal<T>;
+    /** This one can't be picked. */
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    protected readonly group: ToggleButtonGroupHost<T>;
+    readonly element: HTMLElement;
+    /** `button` for a `<button>` the host gave no type; the host's own type
+        otherwise, and none on any other element. */
+    protected readonly type: string | null;
+    /** The group holds this item's value. */
+    readonly checked: Signal<boolean>;
+    /** Out of the choices: its own `aria-disabled`, or the group's. */
+    readonly blocked: Signal<boolean>;
+    focus(options?: FocusOptions): void;
+    protected onClick(event: MouseEvent): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ToggleButtonGroupItem<any>, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ToggleButtonGroupItem<any>, never, never, { "value": { "alias": "value"; "required": true; "isSignal": true; }; "disabled": { "alias": "aria-disabled"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+/**
+ * A round choice holding an icon: a circle as wide as the track is tall
+ * (`--hk-tgb-size`). The icon sits in a box of the item's own
+ * (`[data-slot=icon]`, `--hk-tgb-icon-size`), whose font size and colour it
+ * takes: a `mat-icon` marked `inline`, a font icon's `<i>`, or an SVG sized
+ * `1em` fits with no rule of the host's. It has no words, so name it:
+ * `aria-label` (and a `title` for a tooltip).
+ *
+ * ```html
+ * <button hkTgbIcon value="light" aria-label="Light"><mat-icon inline>light_mode</mat-icon></button>
+ * ```
+ *
+ * A component on the host's element, not a directive: it brings its own
+ * encapsulated look (`:host`), which nothing outside could give an element
+ * the host wrote.
+ */
+declare class ToggleButtonGroupIcon<T = unknown> extends ToggleButtonGroupItem<T> {
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ToggleButtonGroupIcon<any>, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ToggleButtonGroupIcon<any>, "[hkTgbIcon]", ["hkTgbIcon"], {}, {}, never, ["*"], true, never>;
+}
+/**
+ * A pill-shaped choice holding words — as wide as its text, padded by
+ * `--hk-tgb-padding`.
+ *
+ * ```html
+ * <button hkTgbText value="auto">Auto</button>
+ * ```
+ */
+declare class ToggleButtonGroupText<T = unknown> extends ToggleButtonGroupItem<T> {
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ToggleButtonGroupText<any>, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ToggleButtonGroupText<any>, "[hkTgbText]", ["hkTgbText"], {}, {}, never, ["*"], true, never>;
+}
+
+/**
+ * A toggle button group: one of a few choices on a track, the picked one
+ * under a thumb that slides — and changes shape — to whichever is picked
+ * next. The pricing page's Monthly | Yearly; a theme's ☀ | ☾ | Auto.
+ *
+ * ```html
+ * <hk-tgb aria-label="Appearance" [(value)]="appearance">
+ *   <button hkTgbIcon value="light" aria-label="Light"><i class="icon-sun"></i></button>
+ *   <a hkTgbIcon value="dark" aria-label="Dark" href="?theme=dark"><mat-icon inline>dark_mode</mat-icon></a>
+ *   <button hkTgbText value="auto">Auto</button>
+ * </hk-tgb>
+ * ```
+ *
+ * **The group is the control; the items are the host's own elements.** Any
+ * element becomes a choice by wearing one of two attributes — `hkTgbIcon`,
+ * a circle around an icon, or `hkTgbText`, a pill around words — and
+ * registers by being content, so the host writes the items as it would
+ * plain buttons or links. A pick is all a click does: a group inside a
+ * menu leaves the menu open.
+ *
+ * **A signal-forms control, optionally.** It implements `FormValueControl`:
+ * bind a field with `[formField]="settings.theme"` and the directive drives
+ * `value` both ways, pushes `disabled`, `readonly`, `required`, `invalid`
+ * and `touched` in, and hears `touch` when focus leaves the group. Without
+ * a form, `[(value)]` alone is the whole contract. The value is whatever
+ * the items carry — strings, an enum, objects — matched by identity; a
+ * value no item carries picks none.
+ *
+ * **Radio semantics.** The group is a `radiogroup`, each item a `radio`
+ * with `aria-checked`, and one tab stop: the picked item (the first
+ * enabled one while none is). The arrow keys of the group's `orientation`
+ * move the pick — Left and Right across, mirrored right to left; Up and
+ * Down down a vertical group — Home and End go to the ends, Space and
+ * Enter pick in place. The arrows across the other way are left alone for
+ * whatever the group sits in: a vertical menu moves on with them. A key
+ * the group acted on is spent: it does not travel on to a menu or toolbar
+ * around it, whose Space or Enter would act a second time.
+ *
+ * **The thumb follows the picked item's box.** Items differ in size — a
+ * circle, a pill as wide as its words — so the group reads the picked
+ * item's box once per pick, and again only when an item resizes (a font
+ * arriving, a language switched); the thumb slides there by CSS, its size
+ * and corner easing from one shape to the other, and stands still for
+ * reduced motion. It takes its first place without sliding.
+ *
+ * **Each part styles itself, encapsulated.** The group draws the track
+ * and the thumb; each item is a component on the host's element and brings
+ * its shape with it, so nothing reaches past an encapsulation boundary.
+ * Every look is a `--hk-tgb-*` token, defaulting to Material's system
+ * tokens, then a light-dark() pair.
+ *
+ * **State on the host:** `aria-disabled`, `aria-readonly`,
+ * `aria-required`, `aria-invalid` (invalid *and* touched, so nothing
+ * shouts early), `data-orientation`, and `data-empty` while nothing is
+ * picked. No Material, no icon font, no headless library.
+ */
+declare class ToggleButtonGroup<T = unknown> implements FormValueControl<T> {
+    #private;
+    /** The picked item's value. Two-way; the form's value. */
+    readonly value: _angular_core.ModelSignal<T>;
+    /** Which way the items line up, and so which arrow keys are the
+        group's. */
+    readonly orientation: _angular_core.InputSignal<"horizontal" | "vertical">;
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** The pick holds: the items can be reached and read, not changed. */
+    readonly readonly: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    readonly required: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    readonly invalid: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    readonly touched: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Focus left the group. The directive marks the field touched on it. */
+    readonly touch: _angular_core.OutputEmitterRef<void>;
+    /** The items, in the order they stand. */
+    protected readonly items: _angular_core.Signal<readonly ToggleButtonGroupItem<T>[]>;
+    /** The item the group's value picks, if any. */
+    protected readonly picked: _angular_core.Signal<ToggleButtonGroupItem<T> | undefined>;
+    /** The one item Tab lands on: the picked one, else the first that can be
+        picked — none while every one is disabled. */
+    readonly tabStop: _angular_core.Signal<ToggleButtonGroupItem<T>>;
+    constructor();
+    /** Picks a value — an item's click, a key. A no-op while disabled or
+        read-only. */
+    select(value: T): void;
+    /** Puts focus on the group's tab stop. */
+    focus(options?: FocusOptions): void;
+    protected onKeydown(event: KeyboardEvent): void;
+    protected onFocusout(event: FocusEvent): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ToggleButtonGroup<any>, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ToggleButtonGroup<any>, "hk-tgb", never, { "value": { "alias": "value"; "required": true; "isSignal": true; }; "orientation": { "alias": "orientation"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "required": { "alias": "required"; "required": false; "isSignal": true; }; "invalid": { "alias": "invalid"; "required": false; "isSignal": true; }; "touched": { "alias": "touched"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "touch": "touch"; }, ["items"], ["*"], true, never>;
+}
+
+export { TOGGLE_BUTTON_GROUP, ToggleButtonGroup, ToggleButtonGroupIcon, ToggleButtonGroupItem, ToggleButtonGroupText };
+export type { ToggleButtonGroupHost };