@hyalo/angular 0.0.0-stage → 0.1.0

package/types/hyalo-angular-tabs.d.ts

@@ -0,0 +1,102 @@
+import * as i1 from "@angular/aria/tabs";
+import { TabPanel } from "@angular/aria/tabs";
+import * as i0 from "@angular/core";
+/**
+ * One tab and its panel. The panel content is rendered up front and hidden
+ * with `inert` while another tab is selected.
+ */
+export declare class HyTab {
+  readonly panel: TabPanel;
+  /** Text of the tab button. */
+  readonly label: import("@angular/core").InputSignal<string>;
+  /** Optional icon name shown before the label. */
+  readonly icon: import("@angular/core").InputSignal<string | undefined>;
+  /** Disables this tab. Arrow keys skip it. */
+  readonly disabled: import("@angular/core").InputSignalWithTransform<boolean, unknown>;
+  static ɵfac: i0.ɵɵFactoryDeclaration<HyTab, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<HyTab, "hy-tab", never, {
+    "label": {
+      "alias": "label";
+      "required": true;
+      "isSignal": true;
+    };
+    "icon": {
+      "alias": "icon";
+      "required": false;
+      "isSignal": true;
+    };
+    "disabled": {
+      "alias": "disabled";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {}, never, ["*"], true, [{
+    directive: typeof i1.TabPanel;
+    inputs: {
+      "value": "value";
+    };
+    outputs: {};
+  }]>;
+}
+/**
+ * Tabs with a sliding glass indicator, built on Angular Aria. Arrow keys
+ * move between tabs (mirrored in RTL), Home and End jump to the ends.
+ *
+ * ```html
+ * <hy-tabs label="Watch details" [(selected)]="tab">
+ *   <hy-tab value="overview" label="Overview">...</hy-tab>
+ *   <hy-tab value="specs" label="Specifications">...</hy-tab>
+ * </hy-tabs>
+ * ```
+ *
+ * With `selectionMode="follow"` (the default) a tab opens as soon as it is
+ * focused. Use `explicit` when panels are expensive, so users press Enter or
+ * Space to open one.
+ */
+export declare class HyTabs {
+  protected readonly tabs: import("@angular/core").Signal<readonly HyTab[]>;
+  private readonly list;
+  private readonly tabEls;
+  /** Accessible name for the tab list. */
+  readonly label: import("@angular/core").InputSignal<string | undefined>;
+  /** Value of the selected tab. Two-way bindable. Defaults to the first tab. */
+  readonly selected: import("@angular/core").ModelSignal<string | undefined>;
+  /** `follow` opens a tab on focus, `explicit` waits for Enter or Space. */
+  readonly selectionMode: import("@angular/core").InputSignal<"follow" | "explicit">;
+  /** Stretch tabs to fill the row. */
+  readonly stretch: import("@angular/core").InputSignalWithTransform<boolean, unknown>;
+  /** The selected value, falling back to the first enabled tab. */
+  protected readonly current: import("@angular/core").Signal<string | undefined>;
+  protected readonly ready: import("@angular/core").Signal<boolean>;
+  static ɵfac: i0.ɵɵFactoryDeclaration<HyTabs, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<HyTabs, "hy-tabs", never, {
+    "label": {
+      "alias": "label";
+      "required": false;
+      "isSignal": true;
+    };
+    "selected": {
+      "alias": "selected";
+      "required": false;
+      "isSignal": true;
+    };
+    "selectionMode": {
+      "alias": "selectionMode";
+      "required": false;
+      "isSignal": true;
+    };
+    "stretch": {
+      "alias": "stretch";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {
+    "selected": "selectedChange";
+  }, ["tabs"], ["*"], true, [{
+    directive: typeof i1.Tabs;
+    inputs: {};
+    outputs: {};
+  }]>;
+}
+/** Everything needed to build tabs. */
+export declare const HY_TABS: readonly [typeof HyTabs, typeof HyTab];

package/types/hyalo-angular-theme.d.ts

@@ -0,0 +1,46 @@
+import * as i0 from "@angular/core";
+/** The palettes in `styles/palettes/`. Apps can add their own names too. */
+export type HyPaletteName = 'aurora' | 'ember' | 'orchid' | 'ocean' | 'rose' | 'graphite';
+/** Where a palette stylesheet is served from when no `paletteHref` is configured. */
+export declare function defaultPaletteHref(name: string): string;
+/**
+ * Switches palettes, loading each stylesheet the first time it is needed.
+ *
+ * Palettes are separate files in `styles/palettes/`, so they never add to
+ * the initial CSS. Their rules only match while `data-hy-palette` is on
+ * `<html>`, which means a loaded palette costs nothing until it is picked.
+ * The attribute is set only after the file has loaded, so the page never
+ * shows half a palette, and switching back to a palette is instant.
+ *
+ * To restore a saved palette before the app boots, an inline script can add
+ * `<link rel="stylesheet" data-hy-palette="ocean" href="...">` to the head
+ * and the attribute to `<html>`. HyPalette picks up both.
+ */
+export declare class HyPalette {
+  private readonly document;
+  private readonly config;
+  private readonly isBrowser;
+  private readonly loads;
+  private readonly _current;
+  private readonly _selected;
+  /** The palette on screen, or null for the built-in one. */
+  readonly current: import("@angular/core").Signal<string | null>;
+  /**
+   * The palette last asked for. It changes straight away, while `current`
+   * waits for the stylesheet, so a picker can show the choice immediately.
+   */
+  readonly selected: import("@angular/core").Signal<string | null>;
+  /**
+   * Loads a palette and applies it, or goes back to the built-in palette for
+   * null. When several calls overlap, the last one wins. Rejects when the
+   * stylesheet fails to load, and leaves the current palette in place. The
+   * exception is a palette restored before boot whose file never loaded: the
+   * page goes back to the built-in palette instead of claiming it.
+   */
+  use(name: HyPaletteName | (string & {}) | null): Promise<void>;
+  /** Starts loading a palette without applying it, for example on hover. */
+  preload(name: HyPaletteName | (string & {})): void;
+  private load;
+  static ɵfac: i0.ɵɵFactoryDeclaration<HyPalette, never>;
+  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
+}

package/types/hyalo-angular-toast.d.ts

@@ -0,0 +1,79 @@
+import * as i0 from "@angular/core";
+/** Colour and icon of a toast. */
+export type HyToastTone = 'neutral' | 'info' | 'success' | 'warning' | 'danger';
+/** What to show. */
+export interface HyToastOptions {
+  readonly message: string;
+  readonly title?: string;
+  readonly tone?: HyToastTone;
+  /**
+   * Milliseconds before it hides. 0 keeps it until dismissed. Defaults to
+   * 5000, or 0 when there is an action, so nobody has to race a timer.
+   */
+  readonly duration?: number;
+  /** One optional action, such as Undo. */
+  readonly action?: {
+    readonly label: string;
+    readonly run: () => void;
+  };
+}
+/** @internal One toast in the stack. */
+export interface HyToastItem extends HyToastOptions {
+  readonly id: number;
+  readonly leaving: boolean;
+}
+/** Handle to a shown toast. */
+export interface HyToastRef {
+  dismiss(): void;
+}
+/** @internal Why the timers are on hold. Hover and focus are tracked apart. */
+export type HyToastHold = 'hover' | 'focus';
+/**
+ * Shows toasts: short messages about something that just happened.
+ *
+ * ```ts
+ * toaster.show({ message: 'Address saved', tone: 'success' });
+ * toaster.show({ message: 'Draft deleted', action: { label: 'Undo', run: () => restore() } });
+ * ```
+ *
+ * Every toast is announced through the live announcer (`danger` toasts
+ * assertively, the rest politely). Timers pause while the pointer or focus
+ * is in the stack, and toasts can be swiped away. The stack sits at the
+ * bottom inline-end corner and is a labelled region, so keyboard and screen
+ * reader users can reach the actions.
+ */
+export declare class HyToaster {
+  private readonly injector;
+  private readonly announcer;
+  private readonly isBrowser;
+  private readonly timers;
+  private overlayRef;
+  private nextId;
+  private readonly holds;
+  /** @internal The current stack, newest last. */
+  readonly items: import("@angular/core").WritableSignal<readonly HyToastItem[]>;
+  /** Shows a toast. Does nothing during server rendering. */
+  show(options: HyToastOptions): HyToastRef;
+  success(message: string, title?: string): HyToastRef;
+  error(message: string, title?: string): HyToastRef;
+  /** Hides one toast with its exit animation, a fade with reduced motion. */
+  dismiss(id: number): void;
+  /** @internal Removes a toast that already left the screen, as after a swipe. */
+  discard(id: number): void;
+  private clearTimer;
+  /** Hides every toast. */
+  dismissAll(): void;
+  /**
+   * @internal Pauses all timers while the stack is hovered or focused. Each
+   * reason is held separately, so the pointer leaving does not restart the
+   * timers while focus is still on a toast.
+   */
+  pause(reason: HyToastHold): void;
+  /** @internal Releases one hold. Timers restart once no hold is left. */
+  resume(reason: HyToastHold): void;
+  private startTimer;
+  private remove;
+  private ensureStack;
+  static ɵfac: i0.ɵɵFactoryDeclaration<HyToaster, never>;
+  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
+}

package/types/hyalo-angular.d.ts

@@ -0,0 +1,345 @@
+import * as i0 from "@angular/core";
+import { ElementRef, InjectionToken, Provider, Signal } from "@angular/core";
+/**
+ * How see-through a surface is.
+ *
+ * - `clear`: a light veil, most of the background shows through.
+ * - `frosted`: the default glass, blurred and saturated.
+ * - `tinted`: frosted glass coloured by the primary colour.
+ * - `solid`: opaque. Used automatically when the browser cannot blur, when
+ *   the user asks for reduced transparency, and on the low fidelity tier.
+ */
+export type HyMaterial = 'clear' | 'frosted' | 'tinted' | 'solid';
+/**
+ * How heavy a glass surface reads. Bigger surfaces should be thicker: more
+ * blur and a deeper shadow.
+ *
+ * - `thin`: chips and buttons.
+ * - `regular`: the default, for cards, bars, popovers and toasts.
+ * - `thick`: dialogs, drawers and sheets.
+ */
+export type HyThickness = 'thin' | 'regular' | 'thick';
+/** Control size. All sizes keep a touch target of at least 32px. */
+export type HySize = 'sm' | 'md' | 'lg';
+/**
+ * Colour role of a control. `secondary` uses --hy-secondary when the theme sets
+ * it and falls back to the primary colour when it does not.
+ */
+export type HyTone = 'primary' | 'secondary' | 'neutral' | 'success' | 'warning' | 'danger';
+/**
+ * How much visual effort the device can afford.
+ *
+ * - `high`: everything, including cursor physics and (from v0.2) WebGL.
+ * - `medium`: GSAP tilt and reveals, no WebGL.
+ * - `low`: CSS only. Glass turns solid and nothing waits on JavaScript to
+ *   become visible.
+ */
+export type HyFidelityTier = 'high' | 'medium' | 'low';
+/**
+ * The small part of GSAP that Hyalo uses. Declared here so the kit compiles
+ * without GSAP installed. The real `gsap` object satisfies it.
+ */
+export interface HyGsap {
+  to(target: Element | Element[], vars: Record<string, unknown>): unknown;
+  set(target: Element | Element[], vars: Record<string, unknown>): unknown;
+  quickTo(target: Element, property: string, vars?: Record<string, unknown>): (value: number) => unknown;
+  killTweensOf(target: Element | Element[]): void;
+}
+/** Returns GSAP, usually through a dynamic import so it lands in its own chunk. */
+export type HyGsapLoader = () => Promise<HyGsap>;
+/** Global defaults read by every Hyalo component. */
+export interface HyConfig {
+  /** Default material for glass surfaces. */
+  readonly material: HyMaterial;
+  /** Default control size. */
+  readonly size: HySize;
+  /** Default tone for buttons and other coloured controls. */
+  readonly tone: HyTone;
+  /**
+   * Forces a fidelity tier instead of detecting it. Handy for tests,
+   * screenshots and low-end kiosks.
+   */
+  readonly fidelity?: HyFidelityTier;
+  /**
+   * Loads GSAP on demand. Without it, Hyalo falls back to CSS transitions,
+   * so GSAP stays an optional dependency.
+   *
+   * ```ts
+   * provideHyalo({ gsap: () => import('gsap').then((m) => m.gsap) })
+   * ```
+   */
+  readonly gsap?: HyGsapLoader;
+  /**
+   * Maps a palette name to its stylesheet URL for HyPalette. Defaults to
+   * `palette-<name>.css`, which is what a non-injected `bundleName` entry
+   * in angular.json produces.
+   */
+  readonly paletteHref?: (name: string) => string;
+}
+/** Resolved Hyalo configuration. Use {@link provideHyalo} to change it. */
+export declare const HY_CONFIG: InjectionToken<HyConfig>;
+/**
+ * Sets Hyalo defaults. Works in `app.config.ts` and in a component's
+ * `providers`, where it merges with whatever the parent injector provides.
+ * That makes it easy to switch one section of a page to `solid`, for example.
+ */
+export declare function provideHyalo(config?: Partial<HyConfig>): Provider;
+/**
+ * Returns a unique id with the given prefix. The counter is per application,
+ * so the server and the client produce the same ids during hydration.
+ */
+export declare function injectId(prefix: string): string;
+interface NavigatorHints {
+  readonly deviceMemory?: number;
+  readonly hardwareConcurrency?: number;
+  readonly connection?: {
+    readonly saveData?: boolean;
+  };
+}
+/**
+ * Picks a tier from what the browser reports. Exported for tests and for
+ * apps that want to run the same check themselves.
+ *
+ * Reduced motion is not a reason to drop a tier: it asks for less movement,
+ * not for less glass. HyMotion already turns off decorative motion for it,
+ * and reduced transparency is handled in CSS.
+ */
+export declare function detectFidelity(nav: NavigatorHints): HyFidelityTier;
+/**
+ * Holds the current fidelity tier. Every effect in Hyalo reads it.
+ *
+ * The server and the first client render always use `medium`, so hydration
+ * sees the same markup. The real tier is detected right after the first
+ * render. The tier is also written to `data-hy-fidelity` on `<html>` for
+ * CSS that needs it.
+ */
+export declare class HyFidelity {
+  private readonly config;
+  private readonly document;
+  private readonly _tier;
+  private overridden;
+  /** The active tier. */
+  readonly tier: import("@angular/core").Signal<HyFidelityTier>;
+  constructor();
+  /** Overrides the detected tier, for example from a settings toggle. */
+  setTier(tier: HyFidelityTier): void;
+  static ɵfac: i0.ɵɵFactoryDeclaration<HyFidelity, never>;
+  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
+}
+/** One named motion: duration in seconds plus matching GSAP and CSS easings. */
+export interface HyMotionPreset {
+  readonly duration: number;
+  readonly ease: string;
+  readonly css: string;
+}
+/**
+ * The shared motion vocabulary. CSS has the same values as `--hy-dur-*` and
+ * `--hy-ease-*` tokens.
+ *
+ * - `settle`: the default for anything that moves into place.
+ * - `pop`: a small overshoot. Only for motion the user caused, such as a
+ *   toggle they just pressed. Never for things that appear on their own.
+ * - `quick`: acknowledgements, like a press or a hover.
+ * - `scene`: large, slow movements such as section reveals.
+ */
+export declare const MOTION: {
+  readonly settle: {
+    readonly duration: 0.44;
+    readonly ease: "power3.out";
+    readonly css: "cubic-bezier(0.215, 0.61, 0.355, 1)";
+  };
+  readonly pop: {
+    readonly duration: 0.5;
+    readonly ease: "back.out(1.5)";
+    readonly css: "cubic-bezier(0.34, 1.56, 0.64, 1)";
+  };
+  readonly quick: {
+    readonly duration: 0.22;
+    readonly ease: "power2.out";
+    readonly css: "cubic-bezier(0.25, 0.46, 0.45, 0.94)";
+  };
+  readonly scene: {
+    readonly duration: 0.9;
+    readonly ease: "expo.out";
+    readonly css: "cubic-bezier(0.16, 1, 0.3, 1)";
+  };
+};
+/**
+ * Motion state for the whole app: whether the user prefers reduced motion,
+ * whether effects may run at all, and lazy access to GSAP.
+ */
+export declare class HyMotion {
+  private readonly config;
+  private readonly fidelity;
+  private readonly document;
+  private readonly isBrowser;
+  private readonly _reduced;
+  private gsapPromise;
+  /** True when the OS asks for reduced motion, or the app forced it. */
+  readonly reduced: import("@angular/core").Signal<boolean>;
+  /** True when decorative motion (tilt, magnetic, reveal) may run. */
+  readonly enabled: import("@angular/core").Signal<boolean>;
+  constructor();
+  /**
+   * Forces reduced or full motion regardless of the OS setting, and mirrors
+   * the choice to `data-hy-motion` so CSS tokens follow. Pass `null` to go
+   * back to the OS setting.
+   */
+  setReduced(reduced: boolean | null): void;
+  /**
+   * Loads GSAP once, if the app provided a loader. Resolves to `null` on the
+   * server, without a loader, or if loading fails, so callers can fall back
+   * to CSS.
+   */
+  gsap(): Promise<HyGsap | null>;
+  static ɵfac: i0.ɵɵFactoryDeclaration<HyMotion, never>;
+  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
+}
+/**
+ * A spring in the two numbers Apple designs with.
+ *
+ * - `damping`: 1 settles without overshoot, lower values bounce.
+ * - `response`: roughly how many seconds it takes to get there. Not a
+ *   duration; the settle time falls out of the physics.
+ */
+export interface HySpringConfig {
+  readonly damping: number;
+  readonly response: number;
+}
+/**
+ * The shared springs.
+ *
+ * - `settle`: the default. No bounce.
+ * - `momentum`: after a flick or a drag, when the gesture carried speed.
+ */
+export declare const SPRINGS: {
+  readonly settle: {
+    readonly damping: 1;
+    readonly response: 0.4;
+  };
+  readonly momentum: {
+    readonly damping: 0.8;
+    readonly response: 0.3;
+  };
+};
+/** Options for {@link HySpring.to}. */
+export interface HySpringTarget extends Partial<HySpringConfig> {
+  /** Starting velocity in units per second. Defaults to the current one. */
+  readonly velocity?: number;
+  /** Runs once the value comes to rest on the target. */
+  readonly onRest?: () => void;
+}
+/**
+ * Animates one number on `requestAnimationFrame`. Every `to()` starts from
+ * the live value and keeps its velocity, so the motion can be grabbed and
+ * redirected at any moment without a jump or a sudden stop.
+ */
+export declare class HySpring {
+  private readonly onUpdate;
+  /** The value on screen right now. */
+  value: number;
+  /** Units per second. */
+  velocity: number;
+  private target;
+  private config;
+  private onRest;
+  private frame;
+  private last;
+  constructor(initial: number, onUpdate: (value: number) => void);
+  /** True while the spring is moving. */
+  get running(): boolean;
+  /** Springs toward `target`, from wherever it is now. */
+  to(target: number, options?: HySpringTarget): void;
+  /** Jumps to a value and stops, as when a finger holds it. */
+  set(value: number): void;
+  /** Stops where it is. A pending `onRest` is dropped. */
+  stop(): void;
+  private readonly tick;
+}
+/**
+ * How far a flick travels before it stops, from the velocity in px per
+ * second. This is the deceleration curve of scrolling, so a target picked
+ * from `position + project(velocity)` lands where the gesture was going.
+ */
+export declare function project(velocity: number, decelerationRate?: number): number;
+/**
+ * Resistance past a boundary. The further the overshoot, the less the
+ * element follows, so an edge feels soft instead of frozen.
+ */
+export declare function rubberband(overshoot: number, dimension: number, constant?: number): number;
+/** Velocity of a pointer from its last 100ms of movement. */
+export declare class HyVelocityTracker {
+  private samples;
+  add(value: number, time?: number): void;
+  reset(): void;
+  /** Units per second. Zero if the pointer has been still for 100ms. */
+  velocity(now?: number): number;
+}
+/**
+ * Turns any element into a glass surface.
+ *
+ * ```html
+ * <aside hyMaterial="clear">...</aside>
+ * <section hyMaterial thickness="thick">...</section>
+ * ```
+ *
+ * The look lives in CSS (`.hy-glass[data-material]`), so effects stay cheap
+ * and themeable. On the low fidelity tier every material renders as `solid`,
+ * because backdrop blur is the most expensive thing on the page.
+ */
+export declare class HyMaterialDirective {
+  private readonly config;
+  private readonly fidelity;
+  /** The material. An empty attribute uses the configured default. */
+  readonly material: import("@angular/core").InputSignal<"" | HyMaterial | undefined>;
+  /** How heavy the glass reads. Use `thick` for large surfaces. */
+  readonly thickness: import("@angular/core").InputSignal<HyThickness>;
+  /** The material that is actually rendered after fidelity is applied. */
+  readonly resolved: import("@angular/core").Signal<HyMaterial>;
+  static ɵfac: i0.ɵɵFactoryDeclaration<HyMaterialDirective, never>;
+  static ɵdir: i0.ɵɵDirectiveDeclaration<HyMaterialDirective, "[hyMaterial]", never, {
+    "material": {
+      "alias": "hyMaterial";
+      "required": false;
+      "isSignal": true;
+    };
+    "thickness": {
+      "alias": "thickness";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {}, never, never, true, never>;
+}
+/**
+ * Mirrors interaction state to data attributes so glass effects can stay in
+ * CSS: `data-hover`, `data-press` and `data-focus-visible`.
+ *
+ * Hover is only reported for mouse and pen, so touch screens never get a
+ * stuck hover state.
+ */
+export declare class HyInteractive {
+  private readonly host;
+  private readonly focusMonitor;
+  protected readonly hovered: import("@angular/core").WritableSignal<boolean>;
+  protected readonly pressed: import("@angular/core").WritableSignal<boolean>;
+  protected readonly focusVisible: import("@angular/core").WritableSignal<boolean>;
+  constructor();
+  protected onEnter(event: PointerEvent): void;
+  static ɵfac: i0.ɵɵFactoryDeclaration<HyInteractive, never>;
+  static ɵdir: i0.ɵɵDirectiveDeclaration<HyInteractive, "[hyInteractive]", never, {}, {}, never, never, true, never>;
+}
+/** True in the browser, false during server rendering. Call in an injection context. */
+declare function injectIsBrowser(): boolean;
+/** Reads a media query once. Always false on the server. */
+declare function matchesMedia(query: string): boolean;
+/**
+ * Keeps a sliding indicator under the selected item of a row by writing
+ * `--hy-ind-x` and `--hy-ind-size` on the row. The offset is physical (from
+ * the left edge) and the indicator is placed physically too, so the same
+ * numbers work in both directions.
+ *
+ * Returns a signal that turns true after the first placement, so CSS can
+ * enable the transition only from then on.
+ */
+declare function trackIndicator(container: Signal<ElementRef<HTMLElement> | undefined>, selected: () => HTMLElement | null): Signal<boolean>;
+export { injectIsBrowser as ɵinjectIsBrowser, matchesMedia as ɵmatchesMedia, trackIndicator as ɵtrackIndicator };