@joystyk/ui 0.0.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# @joystyk/ui
+
+## 0.2.0
+
+No changes in this release.
+
+## 0.1.0
+
+### Minor Changes
+
+- Prepare the first compiled library release: ESM and API declarations for every public entry point, runtime assets, and checks against installed npm tarballs. Games and applications remain private.

package/README.md

@@ -1,5 +1,34 @@
 # @joystyk/ui
 
-The first Joystyk library release is not yet available. This placeholder reserves the package name.
+Shared Gyral controls and design tokens. Import a component module once to register its custom element. The button wraps a native button and supports keyboard activation and a pressed state. Ad modules implement contextual slots and their validated wire formats.
 
-Source: https://github.com/joystyk-games/game-libraries
+## npm package
+
+The first `0.1.0` release is being prepared; it has not been published. Once available:
+
+```sh
+npm install @joystyk/ui
+```
+
+Node consumers require Node 24.15 or later. Browser entry points require a modern
+browser and should be loaded in the browser. Tested with Gyral 0.3.1.
+
+| Import | Format |
+| --- | --- |
+| `@joystyk/ui` | ES module and TypeScript declarations |
+| `@joystyk/ui/button` | ES module and TypeScript declarations |
+| `@joystyk/ui/ad-slot` | ES module and TypeScript declarations |
+| `@joystyk/ui/ad-wire` | ES module and TypeScript declarations |
+| `@joystyk/ui/slots` | ES module and TypeScript declarations |
+| `@joystyk/ui/tokens.css` | CSS asset |
+
+Only the entries listed above are public API. Installed packages contain compiled ESM,
+type declarations and runtime assets. Repository-relative links describe the Joystyk
+workspace and are not needed to use the npm package.
+
+```ts
+import '@joystyk/ui/button';
+import '@joystyk/ui/tokens.css';
+
+// In a Gyral view: <jy-button toggle>Sound</jy-button>
+```

package/dist/ad-slot.d.ts

@@ -0,0 +1,129 @@
+import { type Command, type PropsOf } from '@gyral/core';
+import { type AdFill, type AdQuery, type CreativeFill, type HouseFill } from './ad-wire.js';
+import { type SlotId, type SlotSurface } from './slots.js';
+/** Whether the visitor sees ads. 'hide' arrives with ad-free entitlements in v2. */
+export type AdEntitlement = 'show' | 'hide';
+/** Where `<ad-slot>` learns whether to show ads. */
+export interface AdEntitlementSource {
+    get(): AdEntitlement;
+    /** Calls `listener` on every change; returns how to stop. */
+    subscribe(listener: (entitlement: AdEntitlement) => void): () => void;
+}
+/** The v1 source: every visitor sees ads, so it never changes. */
+export declare const alwaysShowAds: AdEntitlementSource;
+/** The default entitlement driver: `alwaysShowAds`. */
+export declare const adEntitlement: import("@gyral/core").Driver<undefined, AdEntitlement, unknown>;
+/** Gives every `<ad-slot>` below `element` its entitlement from `source`. */
+export declare const provideAdEntitlement: (element: Element, source: AdEntitlementSource) => (() => void);
+/** `navigator.onLine` now and on every `online` / `offline` event. */
+export declare const connectivity: import("@gyral/core").Driver<undefined, boolean, unknown>;
+/**
+ * Asks the ad endpoint for a slot's fill and parses the answer at the boundary. No cookies go
+ * with it. Fails on a network error, a non-2xx status or an answer that doesn't parse.
+ */
+export declare const adServer: import("@gyral/core").Driver<string, {
+    kind: "creative";
+    id: number;
+    image: {
+        src: string;
+        width: number;
+        height: number;
+    };
+    alt: string;
+    headline: string;
+    href: string;
+    beacon: string;
+} | {
+    kind: "house";
+    headline: string;
+    text: string;
+    cta: string;
+    href: string;
+} | {
+    kind: "collapse";
+}, string>;
+/** Sends an impression beacon: a bodiless POST that outlives the page, without cookies. */
+export declare const adBeacon: import("@gyral/core").Driver<string, void, string>;
+/** Where the slot's fill stands. */
+export type AdLoad = 
+/** Not near the viewport yet: nothing asked. */
+{
+    readonly _tag: 'Waiting';
+} | {
+    readonly _tag: 'Loading';
+    readonly url: string;
+} | {
+    readonly _tag: 'Filled';
+    readonly url: string;
+    readonly fill: CreativeFill | HouseFill;
+    readonly seen: boolean;
+}
+/** Nothing to show, or something failed: the slot collapses. */
+ | {
+    readonly _tag: 'Empty';
+    readonly url: string;
+};
+export interface AdSlotState {
+    readonly entitlement: AdEntitlement;
+    /** What the connectivity driver last said; null until it first reports (assumed online). */
+    readonly online: boolean | null;
+    /** The box has come near the viewport once. */
+    readonly near: boolean;
+    readonly ad: AdLoad;
+}
+export type AdSlotMsg = {
+    readonly _tag: 'Entitled';
+    readonly entitlement: AdEntitlement;
+} | {
+    readonly _tag: 'Connectivity';
+    readonly online: boolean;
+}
+/** The box came within a screen's reach of the viewport. */
+ | {
+    readonly _tag: 'Near';
+} | {
+    readonly _tag: 'Loaded';
+    readonly url: string;
+    readonly fill: AdFill;
+} | {
+    readonly _tag: 'LoadFailed';
+    readonly url: string;
+}
+/** The creative's image loaded and is at least half on screen, or it failed to load. */
+ | {
+    readonly _tag: 'Image';
+    readonly status: 'seen' | 'broken';
+};
+/** What the slot shows: its reserved box (empty or filled), or nothing at all. Pure. */
+export declare const slotPresentation: (s: AdSlotState) => "reserved" | "collapsed";
+declare const props: {
+    /** The registry id (attribute `slot-id`; `slot` is taken by the platform). */
+    slotId: import("@gyral/core").Prop<SlotId>;
+    /** The kind of page the slot is on (attribute `page`). Default: the slot's first surface. */
+    page: import("@gyral/core").Prop<SlotSurface | undefined>;
+    /** The game the page or screen is about (attribute `game-id`). */
+    gameId: import("@gyral/core").Prop<string | undefined>;
+    /** The category the page is about (attribute `category`). */
+    category: import("@gyral/core").Prop<string | undefined>;
+};
+export type AdSlotProps = PropsOf<typeof props>;
+/** The context the slot sends: what the page is about, never who is looking. */
+export declare const queryOf: (p: AdSlotProps) => AdQuery;
+/** Asks the endpoint for `url`'s fill; the latest request wins. */
+export declare const requestFill: (url: string) => Command<AdSlotMsg>;
+export declare const AdSlot: import("@gyral/core").GyralElementClass<AdSlotState, AdSlotMsg, PropsOf<{
+    /** The registry id (attribute `slot-id`; `slot` is taken by the platform). */
+    slotId: import("@gyral/core").Prop<SlotId>;
+    /** The kind of page the slot is on (attribute `page`). Default: the slot's first surface. */
+    page: import("@gyral/core").Prop<SlotSurface | undefined>;
+    /** The game the page or screen is about (attribute `game-id`). */
+    gameId: import("@gyral/core").Prop<string | undefined>;
+    /** The category the page is about (attribute `category`). */
+    category: import("@gyral/core").Prop<string | undefined>;
+}>, never, "Near" | "Image">;
+declare global {
+    interface HTMLElementTagNameMap {
+        'ad-slot': InstanceType<typeof AdSlot>;
+    }
+}
+export {};