@joystyk/ui 0.0.0-stage → 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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joystyk contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,36 @@
+Third-party material in the Joystyk library release
+
+This notice preserves third-party attribution. Original Joystyk code in the 17
+platform libraries under packages/ uses the MIT license in packages/LICENSE.
+That choice does not license the private applications, games or other repository
+material, and does not replace the third-party terms below.
+
+@joystyk/contracts
+------------------
+Standard Schema v1 type definitions from @standard-schema/spec 1.1.0:
+https://github.com/standard-schema/standard-schema
+https://standardschema.dev
+Copyright (c) 2024 Colin McDonnell. MIT License.
+The complete license and source/change notes accompany the distributed
+dist/standard-schema.d.ts definitions. Changes: individually exported declarations
+and formatting; the declarations themselves are unchanged.
+
+@joystyk/identity and @joystyk/content
+-----------------------------------
+Word blocklists derived from List of Dirty, Naughty, Obscene, and Otherwise Bad
+Words, copyright Shutterstock, Inc. and contributors:
+https://github.com/LDNOOBW/List-of-Dirty-Naughty-Obscene-and-Otherwise-Bad-Words
+Licensed under Creative Commons Attribution 4.0 International:
+https://creativecommons.org/licenses/by/4.0/
+Identity uses the English list at commit
+5faf2ba42d7b1c0977169ec3611df25a3c08eb13. Changes include reducing or dropping
+phrases, dropping words with everyday meanings, substituting stems for inflections
+and adding entries. Identity's README and content's lists/blocklist.txt retain
+their source-specific provenance and changes.
+
+@joystyk/content
+---------------
+SCOWL-derived common, vocabulary and ranked word lists use SCOWL 2020.12.07.
+Their complete source licenses and attribution accompany the package in
+lists/SCOWL-COPYRIGHT. Word-list transformations and build provenance are described
+in the package README. Preserve that copyright file when redistributing the lists.

package/README.md

@@ -1,3 +1,34 @@
-# Temporary Holding Version
+# @joystyk/ui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+
+## 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 {};