@fishies/ui 0.8.3

package/LICENSE

@@ -0,0 +1,26 @@
+The code in this package (everything under src/ and dist/) is under the MIT License:
+
+MIT License
+
+Copyright (c) 2026 Fishies
+
+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.
+
+The icons (everything under icons/) and the Fishies name and marks are
+© 2026 Fishies. All rights reserved.

package/README.md

@@ -0,0 +1,60 @@
+<p align="center">
+  <a href="https://fishies.lol/ui"><img src="https://fishies.lol/ui/banner.webp" alt="Fishies UI: plump buttons, water glass with a gold rim and a painted icon set" width="100%"></a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@fishies/ui"><img src="https://img.shields.io/npm/v/@fishies/ui?style=flat-square&color=f4c656&labelColor=0b2233&label=%40fishies%2Fui" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/@fishies/ui"><img src="https://img.shields.io/npm/dm/@fishies/ui?style=flat-square&color=5cd8c6&labelColor=0b2233&label=downloads" alt="npm downloads"></a>
+  <a href="https://bundlephobia.com/package/@fishies/ui"><img src="https://img.shields.io/bundlephobia/minzip/@fishies/ui?style=flat-square&color=83cfbd&labelColor=0b2233&label=min%2Bgzip" alt="bundle size"></a>
+  <img src="https://img.shields.io/badge/react-18%2B-83cfbd?style=flat-square&labelColor=0b2233" alt="React 18 or newer">
+  <img src="https://img.shields.io/badge/types-included-83cfbd?style=flat-square&labelColor=0b2233" alt="TypeScript types included">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/code-MIT-f4c656?style=flat-square&labelColor=0b2233" alt="code MIT"></a>
+  <a href="https://fishies.lol/ui"><img src="https://img.shields.io/badge/showcase-fishies.lol%2Fui-f4c656?style=flat-square&labelColor=0b2233" alt="live showcase"></a>
+</p>
+
+# @fishies/ui
+
+The kit the social aquarium game [Fishies](https://fishies.lol) is drawn with: reef-toy React
+components, design tokens as CSS variables and as data, and the painted system icon set. See every
+piece live, with the Fishies Handbook, at **https://fishies.lol/ui**.
+
+```sh
+bun add @fishies/ui
+```
+
+<sub>npm i @fishies/ui · pnpm add @fishies/ui · yarn add @fishies/ui</sub>
+
+## Use it
+
+```tsx
+import '@fishies/ui/tokens.css'   // the --fx-* custom properties
+import '@fishies/ui/kit.css'      // the components
+import { Button, Panel, configureIcons } from '@fishies/ui'
+
+// The icons ship in this package under icons/. Serve that folder, or point at a CDN copy:
+configureIcons({ url: icon => `https://cdn.jsdelivr.net/npm/@fishies/ui@0.8.3/icons/${icon.name}.png` })
+
+export function Shop() {
+  return <Panel title="Shop" icon="shop">
+    <Button tone="gold" icon="coin">Buy for 120</Button>
+  </Panel>
+}
+```
+
+React 18 or newer is a peer dependency. Each component is its own module, so a bundler keeps only
+what you import. `Select` and the loader carry their own stylesheets (`@fishies/ui/select.css`,
+`@fishies/ui/loader.css`).
+
+The motion tokens (`--m-quick`, `--m-ease-spring` and the rest) are slots: set them, or load a
+stylesheet that does, and every component animates with them; leave them out and nothing moves.
+
+## What is in it
+
+| Folder | Holds |
+| --- | --- |
+| `dist/` | ES modules with type declarations, and the stylesheets |
+| `src/` | the same components and tokens as TypeScript source |
+| `icons/` | the painted icon set, one PNG per name, each twice its largest display size |
+| `handbook/` | the Fishies Handbook as Markdown |
+
+Version 0.8.3: the minor version follows the Fishies release it was taken from; a patch is a fix to the kit itself.

package/dist/FishiesImg.d.ts

@@ -0,0 +1,9 @@
+import { type ImgHTMLAttributes, type Ref } from 'react';
+import './loader.css';
+export default function FishiesImg({ ref, decoding, ...props }: ImgHTMLAttributes<HTMLImageElement> & {
+    ref?: Ref<HTMLImageElement>;
+}): import("react").JSX.Element;
+export declare function useFxPoster(video: {
+    current: HTMLVideoElement | null;
+}, poster: string | null | undefined): void;
+export declare function useDecodedUrl(url: string | null | undefined): string | null;

package/dist/FishiesImg.js

@@ -0,0 +1,64 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { reveal } from './fx-image.js';
+import './loader.css';
+const useIsomorphicLayoutEffect = typeof window === 'undefined' ? useEffect : useLayoutEffect;
+export default function FishiesImg({ ref, decoding, ...props }) {
+    const own = useRef(null);
+    const mounted = useRef(false);
+    const setRef = useCallback((node) => {
+        own.current = node;
+        if (typeof ref === 'function')
+            ref(node);
+        else if (ref)
+            ref.current = node;
+    }, [ref]);
+    useIsomorphicLayoutEffect(() => {
+        const img = own.current;
+        if (!img)
+            return;
+        if (mounted.current)
+            img.setAttribute('data-fx', 'wait');
+        const first = !mounted.current;
+        mounted.current = true;
+        reveal(img, first && img.complete);
+        const settle = () => reveal(img);
+        img.addEventListener('load', settle);
+        img.addEventListener('error', settle);
+        return () => { img.removeEventListener('load', settle); img.removeEventListener('error', settle); };
+    }, [props.src, props.srcSet]);
+    return _jsx("img", { ...props, ref: setRef, decoding: decoding ?? 'async', "data-fx": "wait", suppressHydrationWarning: true });
+}
+export function useFxPoster(video, poster) {
+    const decoded = useDecodedUrl(poster);
+    useIsomorphicLayoutEffect(() => {
+        const element = video.current;
+        if (!element || !poster)
+            return;
+        const show = () => { if (element.getAttribute('data-fx') === 'wait')
+            element.setAttribute('data-fx', 'fade'); };
+        if (decoded || element.readyState >= 2) {
+            show();
+            return;
+        }
+        element.addEventListener('loadeddata', show);
+        return () => element.removeEventListener('loadeddata', show);
+    }, [video, poster, decoded]);
+}
+export function useDecodedUrl(url) {
+    const [ready, setReady] = useState(null);
+    useEffect(() => {
+        if (!url)
+            return;
+        let live = true;
+        const probe = new Image();
+        probe.decoding = 'async';
+        probe.src = url;
+        const done = () => { if (live)
+            setReady(url); };
+        (typeof probe.decode === 'function' ? probe.decode() : new Promise(resolve => { probe.onload = resolve; })).then(done, done);
+        return () => { live = false; };
+    }, [url]);
+    return url && ready === url ? url : null;
+}

package/dist/Select.d.ts

@@ -0,0 +1,22 @@
+import { type ReactNode } from 'react';
+import './select.css';
+export type SelectOption = {
+    value: string;
+    label: string;
+    disabled?: boolean;
+    icon?: ReactNode;
+};
+type Props = {
+    value: string;
+    onChange: (value: string) => void;
+    options: readonly SelectOption[];
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
+    disabled?: boolean;
+    name?: string;
+    className?: string;
+    size?: 'regular' | 'compact';
+    autoFocus?: boolean;
+};
+export default function Select({ value, onChange, options, disabled, name, className, size, autoFocus, ...aria }: Props): import("react").JSX.Element;
+export {};

package/dist/Select.js

@@ -0,0 +1,95 @@
+'use client';
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { SystemIcon } from './kit.js';
+import { useCallback, useEffect, useId, useLayoutEffect, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+import { placePopup, selectedIndex, selectKey } from './select-state.js';
+import './select.css';
+const TOKENS = ['--fs-select-ink', '--fs-select-muted', '--fs-select-line', '--fs-select-panel', '--fs-select-hover', '--fs-select-accent', '--fs-select-radius', '--fs-select-shadow', '--fs-select-font'];
+export default function Select({ value, onChange, options, disabled, name, className, size = 'regular', autoFocus, ...aria }) {
+    const id = useId();
+    const trigger = useRef(null), list = useRef(null);
+    const [open, setOpen] = useState(false);
+    const [active, setActive] = useState(-1);
+    const [style, setStyle] = useState({});
+    const [up, setUp] = useState(false);
+    const current = options.find(option => option.value === value);
+    const place = useCallback(() => {
+        const button = trigger.current;
+        if (!button)
+            return;
+        const rect = button.getBoundingClientRect();
+        const spot = placePopup(rect, { width: window.innerWidth, height: window.innerHeight }, 320);
+        const computed = getComputedStyle(button);
+        const tokens = {};
+        for (const token of TOKENS) {
+            const resolved = computed.getPropertyValue(token).trim();
+            if (resolved)
+                tokens[token] = resolved;
+        }
+        setUp(spot.up);
+        setStyle({ ...tokens, fontFamily: computed.fontFamily, left: spot.left, minWidth: spot.width, maxWidth: Math.min(360, window.innerWidth - 16), top: spot.top, bottom: spot.bottom, maxHeight: spot.maxHeight });
+    }, []);
+    const show = (index) => { place(); setActive(index); setOpen(true); };
+    const close = (focus) => { setOpen(false); if (focus)
+        trigger.current?.focus(); };
+    const choose = (next) => { if (next !== value)
+        onChange(next); };
+    useLayoutEffect(() => { if (open)
+        place(); }, [open, place]);
+    useLayoutEffect(() => {
+        const popup = list.current;
+        if (!popup || typeof style.left !== 'number')
+            return;
+        const left = Math.max(8, Math.min(style.left, window.innerWidth - 8 - popup.offsetWidth));
+        if (left !== style.left)
+            setStyle(previous => ({ ...previous, left }));
+    }, [style]);
+    useEffect(() => {
+        if (!open)
+            return;
+        const outside = (event) => {
+            const target = event.target;
+            if (!trigger.current?.contains(target) && !list.current?.contains(target))
+                setOpen(false);
+        };
+        window.addEventListener('pointerdown', outside, true);
+        window.addEventListener('resize', place);
+        const scrolled = (event) => { if (!list.current?.contains(event.target))
+            place(); };
+        window.addEventListener('scroll', scrolled, true);
+        return () => { window.removeEventListener('pointerdown', outside, true); window.removeEventListener('resize', place); window.removeEventListener('scroll', scrolled, true); };
+    }, [open, place]);
+    useEffect(() => {
+        if (open && active >= 0)
+            list.current?.querySelector(`[data-index="${active}"]`)?.scrollIntoView({ block: 'nearest' });
+    }, [open, active]);
+    useEffect(() => { if (disabled)
+        setOpen(false); }, [disabled]);
+    const keydown = (event) => {
+        if (event.altKey || event.ctrlKey || event.metaKey)
+            return;
+        const result = selectKey({ open, active }, event.key, options, value);
+        if (!result.handled && result.close !== 'blur')
+            return;
+        if (result.handled) {
+            event.preventDefault();
+            event.stopPropagation();
+        }
+        if (result.open && !open) {
+            show(result.active);
+            return;
+        }
+        setActive(result.active);
+        if (!result.open)
+            close(result.close === 'focus');
+        if (result.choose !== undefined)
+            choose(result.choose);
+    };
+    const labelId = `${id}-label`, valueId = `${id}-value`, listId = `${id}-list`;
+    const labelledby = aria['aria-labelledby'] ?? (aria['aria-label'] ? labelId : undefined);
+    const classes = ['fs-select', size === 'compact' ? 'fs-select-compact' : '', open ? 'is-open' : '', className ?? ''].filter(Boolean).join(' ');
+    return _jsxs(_Fragment, { children: [aria['aria-label'] && !aria['aria-labelledby'] && _jsx("span", { id: labelId, hidden: true, children: aria['aria-label'] }), _jsxs("button", { ref: trigger, type: "button", className: classes, disabled: disabled, autoFocus: autoFocus, "aria-haspopup": "listbox", "aria-expanded": open, "aria-controls": open ? listId : undefined, "aria-labelledby": labelledby ? `${labelledby} ${valueId}` : undefined, "aria-activedescendant": open && active >= 0 ? `${id}-option-${active}` : undefined, onClick: () => open ? close(false) : show(selectedIndex(options, value)), onKeyDown: keydown, children: [current?.icon && _jsx("span", { className: "fs-select-icon", "aria-hidden": "true", children: current.icon }), _jsx("span", { id: valueId, className: "fs-select-value", children: current?.label ?? '' }), _jsx("i", { "aria-hidden": "true", children: "\u25BE" })] }), name && _jsx("input", { type: "hidden", name: name, value: value }), open && typeof document !== 'undefined' && createPortal(_jsx("ul", { ref: list, id: listId, role: "listbox", "aria-labelledby": labelledby, tabIndex: -1, className: `fs-select-popover${up ? ' is-up' : ''}${size === 'compact' ? ' fs-select-compact' : ''}`, style: style, onPointerDown: event => event.preventDefault(), children: options.map((option, index) => _jsxs("li", { id: `${id}-option-${index}`, "data-index": index, role: "option", "aria-selected": option.value === value, "aria-disabled": option.disabled || undefined, className: index === active ? 'is-active' : undefined, onPointerEnter: () => { if (!option.disabled)
+                        setActive(index); }, onClick: () => { if (option.disabled)
+                        return; close(true); choose(option.value); }, children: [option.icon && _jsx("span", { className: "fs-select-icon", "aria-hidden": "true", children: option.icon }), _jsx("span", { children: option.label }), option.value === value && _jsx("b", { "aria-hidden": "true", children: _jsx(SystemIcon, { name: "check", size: 16 }) })] }, option.value)) }), document.body)] });
+}

package/dist/fx-image.d.ts

@@ -0,0 +1,3 @@
+export type FxState = 'wait' | 'fade' | 'ready' | 'error';
+export declare function reveal(img: HTMLImageElement, instant?: boolean): void;
+export declare const FX_IMAGE_SCRIPT: string;

package/dist/fx-image.js

@@ -0,0 +1,25 @@
+export function reveal(img, instant) {
+    if (img.getAttribute('data-fx') !== 'wait' || !img.complete)
+        return;
+    const src = img.currentSrc || img.src;
+    const set = (state) => {
+        if (img.getAttribute('data-fx') === 'wait' && (img.currentSrc || img.src) === src)
+            img.setAttribute('data-fx', state);
+    };
+    if (!img.naturalWidth) {
+        set('error');
+        return;
+    }
+    if (instant) {
+        set('ready');
+        return;
+    }
+    if (typeof img.decode !== 'function') {
+        set('fade');
+        return;
+    }
+    img.decode().then(() => set('fade'), () => set(img.naturalWidth ? 'fade' : 'error'));
+}
+export const FX_IMAGE_SCRIPT = `(function(){var r=${reveal.toString()};` +
+    `function h(e){var t=e.target;if(t&&t.tagName==='IMG'&&t.hasAttribute('data-fx'))r(t)}` +
+    `document.addEventListener('load',h,true);document.addEventListener('error',h,true)})()`;

package/dist/icons.d.ts

@@ -0,0 +1,28 @@
+export type IconGroup = 'care' | 'places' | 'system' | 'things' | 'expressions';
+export declare const ICON_GROUPS: readonly {
+    readonly id: IconGroup;
+    readonly title: string;
+    readonly use: string;
+}[];
+export type SystemIcon = {
+    readonly name: string;
+    readonly file: string;
+    readonly label: string;
+    readonly meaning: string;
+    readonly group: IconGroup;
+};
+export declare const SYSTEM_ICONS: readonly [SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon, SystemIcon];
+export type SystemIconName = (typeof SYSTEM_ICONS)[number]['name'];
+export declare const ICON_SIZES: {
+    readonly xs: 16;
+    readonly sm: 20;
+    readonly md: 28;
+    readonly lg: 46;
+    readonly xl: 84;
+};
+export type IconSize = keyof typeof ICON_SIZES;
+export declare const iconByName: (name: string) => SystemIcon | undefined;
+export declare function configureIcons(options: {
+    url: (icon: SystemIcon) => string;
+}): void;
+export declare const iconUrl: (icon: SystemIcon) => string;

package/dist/icons.generated.d.ts

@@ -0,0 +1,5 @@
+export declare const ICON_FACTS: Readonly<Record<string, {
+    readonly px: number;
+    readonly sharpTo: number;
+    readonly usedBy: readonly string[];
+}>>;