@tuuject/koi-core 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Koi 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/README.md

@@ -1,3 +1,17 @@
-# Temporary Holding Version
+# @tuuject/koi-core
 
-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.
+Koi's platform-neutral layer: each component's props contract (`<Name>OwnProps`), the `ChangeDetails` passed to callbacks, the UI copy in `strings`, and the pure helpers behind the components.
+
+`@tuuject/koi-react` builds the DOM components on top of it, and a native package uses the same contracts. There is no DOM, no styling and no headless library here, so the package runs anywhere TypeScript does.
+
+You normally get it transitively. Install it directly only if you write a Koi platform package or want the prop types without the React implementation:
+
+```sh
+pnpm add @tuuject/koi-core
+```
+
+```ts
+import type { ButtonOwnProps } from '@tuuject/koi-core';
+```
+
+Repository and design spec: <https://github.com/tuuject/design>

package/dist/alert.d.ts

@@ -0,0 +1,14 @@
+import type { ReactNode } from 'react';
+export type AlertTone = 'info' | 'warning' | 'error';
+export interface AlertOwnProps {
+    /** info (sky) / warning (yellow) / error (red). Default info. */
+    tone?: AlertTone;
+    title?: ReactNode;
+    children?: ReactNode;
+    /** Replaces the tone icon; null hides it. */
+    icon?: ReactNode | null;
+    /** Usually a small Button, below the text. */
+    action?: ReactNode;
+    /** Shows a close button. */
+    onClose?: () => void;
+}

package/dist/alert.js

@@ -0,0 +1 @@
+export {};

package/dist/avatar.d.ts

@@ -0,0 +1,17 @@
+export type AvatarSize = 'sm' | 'md' | 'lg' | 'xl';
+export type AvatarShape = 'circle' | 'square';
+export interface AvatarOwnProps {
+    /** Image URL. While it loads, or if it fails, the initials show instead. */
+    src?: string;
+    /** Alt text and the source of the fallback initials (the first character for CJK names, otherwise up to two initials). */
+    name?: string;
+    /** sm 28px, md 36px (default), lg 44px, xl 64px. */
+    size?: AvatarSize;
+    /** circle (default) or square (12px corners). */
+    shape?: AvatarShape;
+}
+/**
+ * First character of a CJK name ("咕咕" → "咕"), else the first letters of the first and last words ("Ada Lovelace" → "AL").
+ * A mixed name keeps only its leading initial ("Koi 管理员" → "K"): "K管" reads as neither script's initials.
+ */
+export declare function initials(name: string | undefined): string;

package/dist/avatar.js

@@ -0,0 +1,19 @@
+/**
+ * First character of a CJK name ("咕咕" → "咕"), else the first letters of the first and last words ("Ada Lovelace" → "AL").
+ * A mixed name keeps only its leading initial ("Koi 管理员" → "K"): "K管" reads as neither script's initials.
+ */
+export function initials(name) {
+    const s = (name ?? '').trim();
+    if (!s) {
+        return '?';
+    }
+    // Code points, not UTF-16 units, so a surrogate pair isn't cut in half.
+    const first = (w) => (w ? Array.from(w)[0] : '');
+    const isCjk = (ch) => /[㐀-鿿]/.test(ch);
+    if (isCjk(first(s))) {
+        return first(s);
+    }
+    const words = s.split(/\s+/);
+    const last = words.length > 1 ? first(words[words.length - 1]) : '';
+    return (first(words[0]) + (isCjk(last) ? '' : last)).toUpperCase();
+}

package/dist/badge.d.ts

@@ -0,0 +1,9 @@
+import type { ReactNode } from 'react';
+export type BadgeTone = 'neutral' | 'primary' | 'accent' | 'warning' | 'error' | 'solid';
+export interface BadgeOwnProps {
+    /** Default neutral. */
+    tone?: BadgeTone;
+    /** A 6px dot in the text color before the label. */
+    dot?: boolean;
+    children?: ReactNode;
+}

package/dist/badge.js

@@ -0,0 +1 @@
+export {};

package/dist/button.d.ts

@@ -0,0 +1,32 @@
+import type { ReactNode } from 'react';
+import type { ControlSize } from './common.js';
+export declare const BUTTON_COLORS: readonly ['primary', 'accent', 'secondary', 'warning', 'error'];
+export declare const BUTTON_VARIANTS: readonly ['solid', 'soft', 'outline', 'ghost'];
+export type ButtonColor = (typeof BUTTON_COLORS)[number];
+export type ButtonVariant = (typeof BUTTON_VARIANTS)[number];
+/** pill (radius-full) or rounded (radius-lg, 8px). */
+export type ButtonShape = 'pill' | 'rounded';
+export interface ButtonOwnProps {
+    /** What the action means. Default primary. */
+    color?: ButtonColor;
+    /** How loud it is. Default solid. One solid button per group. */
+    variant?: ButtonVariant;
+    /** control-sm 28 / control-md 36 / control-lg 44. Default md. */
+    size?: ControlSize;
+    /** pill (radius-full) or rounded (radius-lg, 8px). Default rounded, or whatever the surrounding ShapeProvider says. */
+    shape?: ButtonShape;
+    iconStart?: ReactNode;
+    iconEnd?: ReactNode;
+    fullWidth?: boolean;
+    /** Shows a Spinner in place of iconStart, disables the button and marks it busy. */
+    loading?: boolean;
+    disabled?: boolean;
+    children?: ReactNode;
+}
+/** Square icon-only button. Defaults to secondary ghost. */
+export interface IconButtonOwnProps extends Pick<ButtonOwnProps, 'color' | 'variant' | 'size' | 'shape' | 'disabled'> {
+    /** Required: the accessible name, also used as the tooltip. */
+    label: string;
+    icon: ReactNode;
+    children?: never;
+}

package/dist/button.js

@@ -0,0 +1,2 @@
+export const BUTTON_COLORS = ['primary', 'accent', 'secondary', 'warning', 'error'];
+export const BUTTON_VARIANTS = ['solid', 'soft', 'outline', 'ghost'];

package/dist/card.d.ts

@@ -0,0 +1,13 @@
+import type { ReactNode } from 'react';
+export interface CardOwnProps {
+    /** outlined (default) / filled / glass (Koi's frosted panel: put it over imagery or color). */
+    variant?: 'outlined' | 'filled' | 'glass';
+    title?: ReactNode;
+    description?: ReactNode;
+    /** Full-bleed content above the head, e.g. an image. */
+    media?: ReactNode;
+    /** Actions, aligned right. */
+    footer?: ReactNode;
+    padding?: 'default' | 'none';
+    children?: ReactNode;
+}

package/dist/card.js

@@ -0,0 +1 @@
+export {};

package/dist/change-details.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The second argument of Koi's change callbacks (`onCheckedChange`, `onChange`, `onOpenChange`). Koi's own type,
+ * not a headless library's (agent-doc/headless.md, rule 5). `E` is the platform's event: `Event` on the web, a
+ * gesture or press event on native.
+ */
+export interface ChangeDetails<E = unknown> {
+    /**
+     * What caused the change, e.g. `'trigger-press'`, `'escape-key'`. The values come from the headless library and
+     * can differ between versions and platforms: log them or branch on them loosely, don't rely on an exact list.
+     */
+    reason: string;
+    /** The platform event behind the change. */
+    event: E;
+    /** Rejects the change: the component keeps its current value (or stays open / closed). */
+    cancel(): void;
+}

package/dist/change-details.js

@@ -0,0 +1 @@
+export {};

package/dist/chat-bubble.d.ts

@@ -0,0 +1,12 @@
+import type { ReactNode } from 'react';
+export declare const CHAT_BUBBLE_SIDES: readonly ['received', 'sent'];
+export type ChatBubbleSide = (typeof CHAT_BUBBLE_SIDES)[number];
+export interface ChatBubbleOwnProps {
+    children: ReactNode;
+    /**
+     * Whose message it is. `sent` fills with `action` (and wants to sit on the right);
+     * `received` (default) is a muted panel (and wants to sit on the left). Only the look:
+     * alignment is the consumer's layout.
+     */
+    side?: ChatBubbleSide;
+}

package/dist/chat-bubble.js

@@ -0,0 +1 @@
+export const CHAT_BUBBLE_SIDES = ['received', 'sent'];

package/dist/checkbox.d.ts

@@ -0,0 +1,12 @@
+import type { ReactNode } from 'react';
+import type { ChangeDetails } from './change-details.js';
+export interface CheckboxOwnProps<E = unknown> {
+    label?: ReactNode;
+    /** Shown under the label in text-muted. Needs a label. */
+    description?: ReactNode;
+    checked?: boolean;
+    defaultChecked?: boolean;
+    onCheckedChange?: (checked: boolean, details: ChangeDetails<E>) => void;
+    disabled?: boolean;
+    readOnly?: boolean;
+}

package/dist/checkbox.js

@@ -0,0 +1 @@
+export {};

package/dist/common.d.ts

@@ -0,0 +1,2 @@
+/** control-sm 28 / control-md 36 / control-lg 44. Components in one row share a size. */
+export type ControlSize = 'sm' | 'md' | 'lg';

package/dist/common.js

@@ -0,0 +1 @@
+export {};

package/dist/dialog.d.ts

@@ -0,0 +1,21 @@
+import type { ReactNode } from 'react';
+export interface DialogOwnProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    title?: ReactNode;
+    description?: ReactNode;
+    children?: ReactNode;
+    /** Actions, in order: cancel (secondary ghost), then the confirming solid button. Buttons here default to shape="rounded". */
+    footer?: ReactNode;
+    /** sm 400 / md 520 / lg 720. Default md. */
+    size?: 'sm' | 'md' | 'lg';
+    /**
+     * 'alertdialog' for confirmations that need an answer: a tap outside never closes it, and focus starts on the
+     * first footer button, the least destructive action (cancel). Default 'dialog'.
+     */
+    role?: 'dialog' | 'alertdialog';
+    /** false: a tap outside (on the backdrop) doesn't close it. Esc and the × still do. Default true; an alertdialog is never dismissed by a tap outside. */
+    dismissible?: boolean;
+    /** Hide the × button (e.g. for confirmations that need an explicit answer). */
+    hideClose?: boolean;
+}

package/dist/dialog.js

@@ -0,0 +1 @@
+export {};

package/dist/divider.d.ts

@@ -0,0 +1,7 @@
+import type { ReactNode } from 'react';
+export interface DividerOwnProps {
+    /** Default horizontal. Vertical stretches to its row's height. */
+    orientation?: 'horizontal' | 'vertical';
+    /** Text centered in a horizontal divider ("或"). Ignored when vertical. */
+    label?: ReactNode;
+}

package/dist/divider.js

@@ -0,0 +1 @@
+export {};

package/dist/field.d.ts

@@ -0,0 +1,14 @@
+import type { ReactNode } from 'react';
+export interface FieldOwnProps {
+    label?: ReactNode;
+    /** Shown under the control in text-muted. */
+    help?: ReactNode;
+    /** Shown under the control in error-text; marks the control invalid. */
+    error?: ReactNode;
+    /** Adds a red asterisk and marks the control required. */
+    required?: boolean;
+    /** Appends "（选填）" to the label. */
+    optional?: boolean;
+    /** One Input, Textarea or Select; it gets the label, help and error wired to it. */
+    children: ReactNode;
+}

package/dist/field.js

@@ -0,0 +1 @@
+export {};

package/dist/icon.d.ts

@@ -0,0 +1,22 @@
+/**
+ * An icon in Iconify's data format (`IconifyIcon`): the markup inside the <svg> and its viewBox. Any Iconify
+ * set fits (`@iconify-icons/<set>/<name>`), so sets can be mixed, and a hand-drawn SVG is written the same way.
+ * Koi's own icons come from Font Awesome Free Solid (`@iconify-icons/fa7-solid`).
+ */
+export interface IconData {
+    /** Everything inside the <svg>, drawn in currentColor. */
+    body: string;
+    /** viewBox width. Default 16, as in Iconify. */
+    width?: number;
+    /** viewBox height. Default 16, as in Iconify. */
+    height?: number;
+    /** viewBox x origin. Default 0. */
+    left?: number;
+    /** viewBox y origin. Default 0. */
+    top?: number;
+}
+export interface IconOwnProps {
+    icon: IconData;
+    /** px. The box is square and the drawing is centered in it. Default `icon` (16). */
+    size?: number;
+}

package/dist/icon.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+export * from './alert.js';
+export * from './avatar.js';
+export * from './badge.js';
+export * from './button.js';
+export * from './card.js';
+export * from './chat-bubble.js';
+export * from './change-details.js';
+export * from './checkbox.js';
+export * from './common.js';
+export * from './dialog.js';
+export * from './divider.js';
+export * from './field.js';
+export * from './icon.js';
+export * from './input.js';
+export * from './link.js';
+export * from './pagination.js';
+export * from './progress.js';
+export * from './prose.js';
+export * from './radio-group.js';
+export * from './select.js';
+export * from './skeleton.js';
+export * from './spinner.js';
+export * from './strings.js';
+export * from './switch.js';
+export * from './table.js';
+export * from './tabs.js';
+export * from './tag.js';
+export * from './toast.js';
+export * from './tooltip.js';

package/dist/index.js

@@ -0,0 +1,32 @@
+// @tuuject/koi-core: what every Koi platform shares. Each component's props contract (`<Name>OwnProps`), the change
+// details its callbacks pass, the copy it writes and the pure logic behind it. No DOM, no styling, no headless
+// library: @tuuject/koi-react adds the DOM attributes on top, a native package will add its own. Rules: agent-doc/core.md.
+export * from './alert.js';
+export * from './avatar.js';
+export * from './badge.js';
+export * from './button.js';
+export * from './card.js';
+export * from './chat-bubble.js';
+export * from './change-details.js';
+export * from './checkbox.js';
+export * from './common.js';
+export * from './dialog.js';
+export * from './divider.js';
+export * from './field.js';
+export * from './icon.js';
+export * from './input.js';
+export * from './link.js';
+export * from './pagination.js';
+export * from './progress.js';
+export * from './prose.js';
+export * from './radio-group.js';
+export * from './select.js';
+export * from './skeleton.js';
+export * from './spinner.js';
+export * from './strings.js';
+export * from './switch.js';
+export * from './table.js';
+export * from './tabs.js';
+export * from './tag.js';
+export * from './toast.js';
+export * from './tooltip.js';

package/dist/input.d.ts

@@ -0,0 +1,14 @@
+import type { ReactNode } from 'react';
+import type { ControlSize } from './common.js';
+export interface InputOwnProps {
+    /** sm 28px / md 36px / lg 44px, the same heights as Button. Default md. */
+    size?: ControlSize;
+    /** Red edge, announced as invalid. Set automatically inside a Field with an error. */
+    invalid?: boolean;
+    iconStart?: ReactNode;
+    iconEnd?: ReactNode;
+}
+export interface TextareaOwnProps {
+    /** Red edge, announced as invalid. Set automatically inside a Field with an error. */
+    invalid?: boolean;
+}

package/dist/input.js

@@ -0,0 +1 @@
+export {};

package/dist/link.d.ts

@@ -0,0 +1,15 @@
+import type { ReactNode } from 'react';
+/**
+ * underline (default): the blog's dashed underline and soft hover tint. plain: secondary text that turns brand on
+ * hover, no underline and no tint; for navigation rows such as breadcrumbs, where a link should read as a muted
+ * label until pointed at.
+ */
+export type LinkVariant = 'underline' | 'plain';
+export interface LinkOwnProps {
+    href?: string;
+    /** Opens outside the app (a new tab on the web), with an arrow glyph and a screen-reader note. */
+    external?: boolean;
+    /** How the link is drawn. Default underline. */
+    variant?: LinkVariant;
+    children?: ReactNode;
+}

package/dist/link.js

@@ -0,0 +1 @@
+export {};

package/dist/pagination.d.ts

@@ -0,0 +1,26 @@
+export type PaginationVariant = 'numbered' | 'simple' | 'compact';
+export interface PaginationOwnProps {
+    /** The current page, 1-based. */
+    page: number;
+    pageCount: number;
+    /** Called with the page to go to. Choosing the current page calls it too (as legacy). */
+    onChange?: (page: number) => void;
+    /**
+     * numbered (default): prev, page numbers, next. simple: the blog's two large pills around "n / m".
+     * compact: page numbers between round icon-only prev/next, all in one tight row of circles.
+     */
+    variant?: PaginationVariant;
+    /** Default "上一页". */
+    prevLabel?: string;
+    /** Default "下一页". */
+    nextLabel?: string;
+    /** How many neighbours to show on each side of the current page. Default 1. */
+    siblings?: number;
+    /** The navigation's accessible name. Default "分页". */
+    label?: string;
+}
+/**
+ * Legacy's pageList, unchanged: the first and last page always, the current page with `sib` neighbours each side,
+ * and a gap ("…a" before, "…b" after) wherever pages are left out, even if only one is.
+ */
+export declare function pageList(page: number, count: number, sib: number): (number | '…a' | '…b')[];

package/dist/pagination.js

@@ -0,0 +1,23 @@
+/**
+ * Legacy's pageList, unchanged: the first and last page always, the current page with `sib` neighbours each side,
+ * and a gap ("…a" before, "…b" after) wherever pages are left out, even if only one is.
+ */
+export function pageList(page, count, sib) {
+    const out = [];
+    const lo = Math.max(2, page - sib);
+    const hi = Math.min(count - 1, page + sib);
+    out.push(1);
+    if (lo > 2) {
+        out.push('…a');
+    }
+    for (let i = lo; i <= hi; i++) {
+        out.push(i);
+    }
+    if (hi < count - 1) {
+        out.push('…b');
+    }
+    if (count > 1) {
+        out.push(count);
+    }
+    return out;
+}

package/dist/progress.d.ts

@@ -0,0 +1,13 @@
+export type ProgressSize = 'sm' | 'md' | 'lg';
+export interface ProgressOwnProps {
+    /** 0–`max`. Omit (or pass null) for an indeterminate bar. */
+    value?: number | null;
+    /** Default 100. */
+    max?: number;
+    /** Shown above the bar and used as its accessible name. Without it the bar is named "进度". */
+    label?: string;
+    /** Show the rounded percentage at the end of the head row (determinate bars only). */
+    showValue?: boolean;
+    /** Track height: sm 4px, md 8px (default), lg 12px. */
+    size?: ProgressSize;
+}

package/dist/progress.js

@@ -0,0 +1 @@
+export {};

package/dist/prose.d.ts

@@ -0,0 +1,11 @@
+import type { ReactNode } from 'react';
+export declare const PROSE_SIZES: readonly ['sm', 'md'];
+export type ProseSize = (typeof PROSE_SIZES)[number];
+export interface ProseOwnProps {
+    children?: ReactNode;
+    /**
+     * The base size everything inside scales from: `md` (default) is 16px for articles and docs, `sm` is 14px for
+     * rich text that sits among UI text (comments, descriptions, assistant replies in a dense panel).
+     */
+    size?: ProseSize;
+}

package/dist/prose.js

@@ -0,0 +1 @@
+export const PROSE_SIZES = ['sm', 'md'];

package/dist/radio-group.d.ts

@@ -0,0 +1,20 @@
+import type { ReactNode } from 'react';
+import type { ChangeDetails } from './change-details.js';
+export interface RadioOption {
+    value: string;
+    label: ReactNode;
+    /** Shown under the label in text-muted. */
+    description?: ReactNode;
+    disabled?: boolean;
+}
+export interface RadioGroupOwnProps<E = unknown> {
+    options: RadioOption[];
+    value?: string;
+    defaultValue?: string;
+    /** Called with the newly chosen value. */
+    onChange?: (value: string, details: ChangeDetails<E>) => void;
+    /** Accessible name of the group (not shown). Inside a Field, the Field's label names it instead. */
+    label?: string;
+    orientation?: 'vertical' | 'horizontal';
+    disabled?: boolean;
+}

package/dist/radio-group.js

@@ -0,0 +1 @@
+export {};

package/dist/select.d.ts

@@ -0,0 +1,72 @@
+import type { ReactNode } from 'react';
+import type { ChangeDetails } from './change-details.js';
+import type { ControlSize } from './common.js';
+export interface SelectOption {
+    value: string;
+    label: string;
+    disabled?: boolean;
+}
+export interface SelectOptionGroup<T extends SelectOption = SelectOption> {
+    label: string;
+    items: T[];
+}
+export type SelectEntry = SelectOption | SelectOptionGroup;
+/** The option type inside `items`: the item itself, or the items of a group. */
+export type SelectOptionOf<I> = I extends SelectOptionGroup<infer T> ? T : I;
+/** The platform's own picker (a native <select> on the web). Its value and change handler are the platform's. */
+export interface SelectOwnProps {
+    /** The choices. */
+    options?: SelectOption[];
+    /** A disabled first option shown until the user picks. */
+    placeholder?: string;
+    /** sm 28px / md 36px / lg 44px, the same heights as Input and Button. Default md. */
+    size?: ControlSize;
+    /** Red edge, announced as invalid. Set automatically inside a Field with an error. */
+    invalid?: boolean;
+}
+/** Koi's own dropdown panel, optionally searchable. */
+export interface SelectPanelOwnProps<I extends SelectEntry = SelectEntry, E = unknown> {
+    /** Options (`{value, label, disabled?}` plus any fields of your own), or groups of them (`{label, items}`). */
+    items: readonly I[];
+    value?: string | null;
+    defaultValue?: string | null;
+    onChange?: (value: string | null, details: ChangeDetails<E>) => void;
+    /** Shown in the trigger until something is chosen. Default "请选择". */
+    placeholder?: ReactNode;
+    /** sm 28px / md 36px / lg 44px, the same heights as Input and Button. Default md. */
+    size?: ControlSize;
+    /** Red edge, announced as invalid. Set automatically inside a Field with an error. */
+    invalid?: boolean;
+    disabled?: boolean;
+    readOnly?: boolean;
+    /** Puts a search box at the top of the panel that filters `items` by label. */
+    searchable?: boolean;
+    /** Default "搜索". Also the search box's accessible name. */
+    searchPlaceholder?: string;
+    /** Shown when the search matches nothing. Default "无匹配项". */
+    emptyText?: ReactNode;
+    /** Draws the chosen option in the trigger. Default: its label. */
+    renderValue?: (item: SelectOptionOf<I>) => ReactNode;
+    /**
+     * Draws the panel. Receives the options to show (filtered by the search, empty groups dropped) in the shape
+     * `items` has; render each as a SelectItem (in SelectGroups, with SelectSeparators, around your own markup).
+     * Default: a SelectItem per option and a SelectGroup per group.
+     */
+    children?: (items: I[]) => ReactNode;
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean, details: ChangeDetails<E>) => void;
+}
+export interface SelectItemOwnProps {
+    /** The option's `value`. */
+    value: string;
+    /** Text for type-to-find when `children` isn't plain text. */
+    label?: string;
+    disabled?: boolean;
+    children: ReactNode;
+}
+export interface SelectGroupOwnProps {
+    /** The heading; it names the group for screen readers. */
+    label: ReactNode;
+    children: ReactNode;
+}

package/dist/select.js

@@ -0,0 +1 @@
+export {};

package/dist/skeleton.d.ts

@@ -0,0 +1,5 @@
+import type { ReactNode } from 'react';
+export interface SkeletonOwnProps {
+    /** Optional: real or placeholder content to size the skeleton by. It is kept in layout but hidden. */
+    children?: ReactNode;
+}

package/dist/skeleton.js

@@ -0,0 +1 @@
+export {};

package/dist/spinner.d.ts

@@ -0,0 +1,7 @@
+export type SpinnerSize = 'sm' | 'md' | 'lg';
+export interface SpinnerOwnProps {
+    /** sm 16 / md 20 / lg 32. Default md. */
+    size?: SpinnerSize;
+    /** Accessible name. Default "加载中". */
+    label?: string;
+}

package/dist/spinner.js

@@ -0,0 +1 @@
+export {};

package/dist/strings.d.ts

@@ -0,0 +1,27 @@
+/** Every piece of copy a component writes on its own (labels, accessible names, defaults). Simplified Chinese, no emoji. */
+export declare const strings: {
+    readonly close: '关闭';
+    readonly loading: '加载中';
+    /** A Button's spinner while `loading`. */
+    readonly processing: '处理中';
+    readonly avatar: '头像';
+    readonly optional: '（选填）';
+    /** Read after an external Link. */
+    readonly opensInNewWindow: '（在新窗口打开）';
+    readonly prevPage: '上一页';
+    readonly nextPage: '下一页';
+    readonly pagination: '分页';
+    readonly page: (n: number) => string;
+    readonly progress: '进度';
+    /** An indeterminate Progress's value text. */
+    readonly inProgress: '进行中';
+    readonly selectPlaceholder: '请选择';
+    readonly search: '搜索';
+    readonly noMatches: '无匹配项';
+    /** Tag's × button; the tag's label follows it. */
+    readonly remove: '移除';
+    /** An empty Table's message. */
+    readonly noData: '暂无数据';
+    /** The toast region's accessible name. */
+    readonly notifications: '通知';
+};

package/dist/strings.js

@@ -0,0 +1,27 @@
+/** Every piece of copy a component writes on its own (labels, accessible names, defaults). Simplified Chinese, no emoji. */
+export const strings = {
+    close: '关闭',
+    loading: '加载中',
+    /** A Button's spinner while `loading`. */
+    processing: '处理中',
+    avatar: '头像',
+    optional: '（选填）',
+    /** Read after an external Link. */
+    opensInNewWindow: '（在新窗口打开）',
+    prevPage: '上一页',
+    nextPage: '下一页',
+    pagination: '分页',
+    page: (n) => `第 ${n} 页`,
+    progress: '进度',
+    /** An indeterminate Progress's value text. */
+    inProgress: '进行中',
+    selectPlaceholder: '请选择',
+    search: '搜索',
+    noMatches: '无匹配项',
+    /** Tag's × button; the tag's label follows it. */
+    remove: '移除',
+    /** An empty Table's message. */
+    noData: '暂无数据',
+    /** The toast region's accessible name. */
+    notifications: '通知',
+};

package/dist/switch.d.ts

@@ -0,0 +1,13 @@
+import type { ReactNode } from 'react';
+import type { ChangeDetails } from './change-details.js';
+export interface SwitchOwnProps<E = unknown> {
+    label?: ReactNode;
+    /** On or off (controlled). */
+    checked?: boolean;
+    /** On or off at first (uncontrolled). */
+    defaultChecked?: boolean;
+    onCheckedChange?: (checked: boolean, details: ChangeDetails<E>) => void;
+    disabled?: boolean;
+    /** Can't be switched, but still focusable. */
+    readOnly?: boolean;
+}

package/dist/switch.js

@@ -0,0 +1 @@
+export {};

package/dist/table.d.ts

@@ -0,0 +1,80 @@
+import type { ReactNode } from 'react';
+/** Where a cell's content sits. Put numbers at `end`. */
+export type TableAlign = 'start' | 'center' | 'end';
+/** A column's sort state. The same shape TanStack Table's `column.getIsSorted()` returns. */
+export type TableSortDirection = 'asc' | 'desc' | false;
+/**
+ * How column widths are decided. `auto` (default): by content, so they shift when the content changes (a skeleton
+ * being replaced, the next page). `fixed`: by the widths you give (the header row's cells, or DataTable's column
+ * `width`); columns without one share what's left. Content that doesn't fit ends in an ellipsis.
+ */
+export type TableLayout = 'auto' | 'fixed';
+/** The table itself. Its parts are plain table elements, so a headless table library can drive them directly. */
+export interface TableOwnProps {
+    /** auto (default) / fixed. Use fixed with column widths when the rows load or page in place. */
+    layout?: TableLayout;
+    children?: ReactNode;
+}
+/** The header, body and footer row groups. */
+export interface TableSectionOwnProps {
+    children?: ReactNode;
+}
+export type TableHeaderOwnProps = TableSectionOwnProps;
+export type TableBodyOwnProps = TableSectionOwnProps;
+export type TableFooterOwnProps = TableSectionOwnProps;
+export type TableCaptionOwnProps = TableSectionOwnProps;
+export interface TableCellOwnProps {
+    /** start (default) / center / end. */
+    align?: TableAlign;
+    /** `none` drops the 8px top and bottom padding, so a 36px control fits the 48px row. Default `default`. */
+    paddingBlock?: 'default' | 'none';
+    children?: ReactNode;
+}
+export interface TableHeaderCellOwnProps<E = unknown> extends TableCellOwnProps {
+    /** The column's current sort. Only shown when the column is sortable (`onSort`). */
+    sort?: TableSortDirection;
+    /**
+     * Makes the header a sort button. Called on press; the platform's event is passed through, so TanStack
+     * Table's `column.getToggleSortingHandler()` can be handed over as is. TanStack v9 returns a handler even for
+     * columns that can't sort, so pass it only when `column.getCanSort()`.
+     */
+    onSort?: (event: E) => void;
+}
+export interface TableRowOwnProps {
+    /** Fills the row with the selection tint. */
+    selected?: boolean;
+    children?: ReactNode;
+}
+export interface TableEmptyOwnProps {
+    /** How many columns the message spans: the table's column count. */
+    colSpan: number;
+    /** Default "暂无数据". */
+    children?: ReactNode;
+}
+export interface DataTableColumn<T> {
+    /** Unique within the table. */
+    key: string;
+    header: ReactNode;
+    cell: (row: T, index: number) => ReactNode;
+    align?: TableAlign;
+    /** The column's width: a number is px, a string any CSS length ('20%'). Pair with the table's `layout="fixed"`. */
+    width?: number | string;
+    /** Sample content for this column's loading placeholder, which takes its size (e.g. '¥199.00'). */
+    skeleton?: ReactNode;
+}
+/** A ready-made table from columns and rows. For sorting, selection or a table library, compose the Table parts instead. */
+export interface DataTableOwnProps<T> {
+    columns: ReadonlyArray<DataTableColumn<T>>;
+    rows: readonly T[];
+    getRowKey: (row: T, index: number) => string | number;
+    /** Shows skeleton rows instead of `rows`. */
+    loading?: boolean;
+    /** How many skeleton rows to show while loading. Default 5. */
+    skeletonRows?: number;
+    /** Shown when there are no rows. Default "暂无数据". */
+    empty?: ReactNode;
+    /** The table's accessible name, read by screen readers only. */
+    caption?: ReactNode;
+    /** auto (default) / fixed. With `fixed` and column widths, columns hold still while rows load and page. */
+    layout?: TableLayout;
+}

package/dist/table.js

@@ -0,0 +1 @@
+export {};

package/dist/tabs.d.ts

@@ -0,0 +1,21 @@
+import type { ReactNode } from 'react';
+import type { ChangeDetails } from './change-details.js';
+export interface TabItem {
+    value: string;
+    label: ReactNode;
+    /** The panel shown while this tab is active. Leave it out on every item for a pure segmented control. */
+    content?: ReactNode;
+    disabled?: boolean;
+}
+export interface TabsOwnProps<E = unknown> {
+    items: TabItem[];
+    value?: string;
+    /** Defaults to the first enabled item. */
+    defaultValue?: string;
+    /** Called with the newly chosen value when the user picks a tab. */
+    onChange?: (value: string, details: ChangeDetails<E>) => void;
+    /** Accessible name of the tab list (not shown). */
+    label?: string;
+    /** Stretch the track to the container and share its width between the tabs. */
+    fullWidth?: boolean;
+}

package/dist/tabs.js

@@ -0,0 +1 @@
+export {};

package/dist/tag.d.ts

@@ -0,0 +1,15 @@
+import type { ReactNode } from 'react';
+export interface TagOwnProps<E = unknown> {
+    children: ReactNode;
+    /** A 14px icon before the label. */
+    icon?: ReactNode;
+    /** The `action-subtle` fill of a chosen filter chip. On its own it's only the look. */
+    selected?: boolean;
+    /**
+     * Makes the tag a toggle for filter chips. Called with the next state when it's pressed; pass `selected` back.
+     * `E` is the platform's press event.
+     */
+    onSelectedChange?: (selected: boolean, event: E) => void;
+    /** Shows a remove (×) button, named "移除 <label>". */
+    onRemove?: () => void;
+}

package/dist/tag.js

@@ -0,0 +1 @@
+export {};

package/dist/toast.d.ts

@@ -0,0 +1,35 @@
+import type { ReactNode } from 'react';
+export type ToastTone = 'info' | 'success' | 'warning' | 'error';
+/** At most this many toasts show; a newer one closes the oldest for good. */
+export declare const TOAST_LIMIT = 4;
+/** ms before a toast closes on its own, unless its options say otherwise. */
+export declare const TOAST_DURATION = 4000;
+export interface ToastOwnProps {
+    /** info and success (brand icon) / warning / error. Default info. */
+    tone?: ToastTone;
+    title?: ReactNode;
+    description?: ReactNode;
+    /** Usually a small Button, at the end of the toast. */
+    action?: ReactNode;
+    /** Shows a close button. */
+    onClose?: () => void;
+}
+export interface ToastOptions {
+    tone?: ToastTone;
+    title?: ReactNode;
+    description?: ReactNode;
+    action?: ReactNode;
+    /** ms before it closes on its own; 0 keeps it until it's closed. Default 4000. */
+    duration?: number;
+}
+export interface ToastProviderOwnProps {
+    children?: ReactNode;
+    /** Where the stack sits, centered. Default bottom. */
+    position?: 'bottom' | 'top';
+}
+/** What `useToast()` returns. */
+export interface ToastApi {
+    /** Shows a toast and returns its id. */
+    toast(options: ToastOptions): number;
+    dismiss(id: number): void;
+}

package/dist/toast.js

@@ -0,0 +1,4 @@
+/** At most this many toasts show; a newer one closes the oldest for good. */
+export const TOAST_LIMIT = 4;
+/** ms before a toast closes on its own, unless its options say otherwise. */
+export const TOAST_DURATION = 4000;

package/dist/tooltip.d.ts

@@ -0,0 +1,22 @@
+import type { ReactElement, ReactNode } from 'react';
+import type { ChangeDetails } from './change-details.js';
+export type TooltipSide = 'top' | 'bottom';
+export interface TooltipOwnProps<E = unknown> {
+    /** A short phrase. Never essential information or interactive content. */
+    content: ReactNode;
+    /** One focusable element (a Button, IconButton, Link…). */
+    children: ReactElement;
+    /** Preferred side; flips to the other one when there's no room. Default top. */
+    side?: TooltipSide;
+    /** Force open or closed (controlled). */
+    open?: boolean;
+    /** Open on first render, then behave as usual. */
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean, details: ChangeDetails<E>) => void;
+    /** Milliseconds of hover before it opens. Default 0: it opens on hover, as in legacy. Keyboard focus always opens it at once. */
+    delay?: number;
+    /** Milliseconds before it closes after the pointer leaves. Default 0. */
+    closeDelay?: number;
+    /** Never open. */
+    disabled?: boolean;
+}

package/dist/tooltip.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@tuuject/koi-core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Koi's platform-neutral layer: each component's props contract, change details, UI copy and pure helpers. Shared by @tuuject/koi-react and the future native package; no DOM, no styling, no headless library.",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.3.0",
+    "typescript": "^7.0.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tuuject/design.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/tuuject/design#readme",
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json"
+  }
 }