@bysages/core 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 By Sages
+
+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

@@ -0,0 +1,59 @@
+# @bysages/core
+
+![npm version](https://img.shields.io/npm/v/@bysages/core)
+![npm downloads](https://img.shields.io/npm/dw/@bysages/core)
+![npm license](https://img.shields.io/npm/l/@bysages/core)
+
+> The visual core of By Sages Elements: the only style layer of the design system, the theme engine, and the lighting engine — framework-agnostic, consumed by every wrapper package.
+
+## Features
+
+- 🎨 **The only visual layer** — every component's stylesheet lives here, native CSS scoped by `[data-scope][data-part]`, so one stylesheet serves React, Vue, Solid, and Svelte alike
+- 🌗 **Theme engine** — `applyTheme()` drives light/dark, accent pigments (qinghua / celadon / zhusha), contrast tiers, density tiers, and scene presets, all expressed as data on the document root
+- 💡 **Lighting engine** — elevation, pigment bleed, and pointer-carried light computed into CSS variables (`setLight`, `attachDynamicLight`); component styles only ever consume light (以光为影 — light as shadow)
+- 🖋️ **Ink ripple** — a press feedback pass that bleeds pigment from the pointer, delegated at the root and tuneable per element
+- 🧩 **Style injection** — `injectComponentStyle()` ships each family's stylesheet at import time, guarded by a head marker so SSR builds that inline styles never double-inject
+
+## Installation
+
+```bash
+# pnpm
+pnpm add @bysages/core @bysages/tokens
+
+# npm
+npm install @bysages/core @bysages/tokens
+
+# yarn
+yarn add @bysages/core @bysages/tokens
+
+# bun
+bun add @bysages/core @bysages/tokens
+```
+
+## Quick Start
+
+Load the compiled tokens, theme the document, and the component styles arrive with the wrappers:
+
+```ts
+import "@bysages/tokens/css";
+import { applyTheme, attachDynamicLight } from "@bysages/core";
+
+applyTheme({ mode: "system", accent: "ink", density: "default" });
+attachDynamicLight();
+```
+
+## Architecture
+
+```
+@bysages/tokens    DTCG source → CSS custom properties
+      ↓
+@bysages/core      theme engine · lighting engine · per-component styles
+      ↓
+wrappers           Vue · React · Solid · Svelte — thin adapters over headless machines
+```
+
+The core owns no interaction; it renders nothing but light. Wrappers bring the headless state machines, the core dresses them.
+
+## License
+
+- [MIT](../../LICENSE) © [By Sages](https://www.bysages.com/)

package/dist/index.d.mts

@@ -0,0 +1,131 @@
+//#region src/theme.d.ts
+/**
+ * Theme engine — the runtime half of the token system. Tokens declare how
+ * themes look (`@layer bs.tokens`); this module drives which theme is active
+ * via data attributes on the root element: `data-theme`, `data-contrast`,
+ * `data-density`, `data-scene`, and `data-accent`.
+ *
+ * @module
+ */
+export type ThemeMode = "light" | "dark" | "system";
+export type ThemeContrast = "auto" | "normal" | "high";
+export type ThemeDensity = "compact" | "default" | "comfortable" | "spacious";
+export type ThemeScene = "auto" | "civic" | "enterprise" | "studio" | "tech";
+export type ThemeAccent = "auto" | "ink" | "qinghua" | "celadon" | "zhusha";
+export interface Theme {
+  mode: ThemeMode;
+  contrast: ThemeContrast;
+  density: ThemeDensity;
+  scene: ThemeScene;
+  accent: ThemeAccent;
+}
+/** Each scene pairs with a default accent — the pigment that carries its
+ * context (civic identity is zhusha, never an error color; tech stays
+ * ink). "auto" accent resolves through this table; explicit accents win. */
+export declare const SCENE_DEFAULT_ACCENT: Record<Exclude<ThemeScene, "auto">, ThemeAccent>;
+/** Each scene also pairs with a contrast tier — civic serves elders, so it
+ * speaks at the loud tier by default. "auto" contrast resolves here;
+ * explicit choices win. */
+export declare const SCENE_DEFAULT_CONTRAST: Record<Exclude<ThemeScene, "auto">, "normal" | "high">;
+export interface ApplyThemeOptions extends Partial<Theme> {
+  /** Persist the theme to localStorage so `initTheme` can restore it. Defaults to true. */
+  persist?: boolean;
+}
+/**
+ * Apply a theme to the document root. Omitted fields keep the current value;
+ * `mode: "system"` resolves against `prefers-color-scheme`, and an "auto"
+ * accent resolves against the active scene.
+ */
+export declare function applyTheme(options?: ApplyThemeOptions): Theme;
+/** Read the active theme (in-memory state first, then root attributes,
+ * then storage). */
+export declare function getTheme(): Theme;
+/**
+ * Restore the persisted theme and keep `mode: "system"` in sync with the OS
+ * while it is active. Safe to call more than once; SSR is a no-op.
+ */
+export declare function initTheme(): void;
+//#endregion
+//#region src/lighting.d.ts
+/**
+ * Lighting engine — the dynamic half of the light pipeline. Every elevation
+ * token computes its shadow from four CSS variables (`--bs-light-x/-y`,
+ * `--bs-light-reach`, `--bs-shadow-ink`), so writing those variables re-lights
+ * the whole interface and every component follows without owning any shadow
+ * code of its own.
+ *
+ * `setLight` places the key light once (a scene's bundled light, or an
+ * application's choice). `attachDynamicLight` lets the pointer carry it:
+ * the element under the cursor is lit locally, its shadow leaning away from
+ * the pointer as the light would cast it.
+ *
+ * @module
+ */
+export interface LightState {
+  /** Shadow offset along x — the direction the light pushes away from. */
+  x?: string;
+  /** Shadow offset along y. */
+  y?: string;
+  /** How far shadows spread; multiplies every elevation's reach. */
+  reach?: number;
+  /** Shadow hue, any CSS color (themes use oklch). */
+  ink?: string;
+}
+/** Place the key light on the document root. Omitted parts keep their
+ * current value. Inline styles set here outrank scene and theme defaults. */
+export declare function setLight(state: LightState): void;
+/** Read the key light currently in force on the document root. */
+export declare function getLight(): LightState;
+/** Remove the inline light so theme and scene declarations take over. */
+export declare function resetLight(): void;
+export interface DynamicLightOptions {
+  /** Largest shadow shift, in px, when the pointer sits at an element's
+   * edge. Defaults to 3 — enough to feel alive, never enough to wobble. */
+  strength?: number;
+}
+/** Let the pointer carry the light across every lit element. Skips touch
+ * pointers and honors `prefers-reduced-motion`; safe to call more than
+ * once (the previous listener is replaced). Returns the detach function. */
+export declare function attachDynamicLight(options?: DynamicLightOptions): () => void;
+/** Stop the pointer from carrying the light and clear any local shifts. */
+export declare function detachDynamicLight(): void;
+//#endregion
+//#region src/ink-ripple.d.ts
+/**
+ * Ink ripple — the press feedback of the paper-and-ink register. Where
+ * Material spreads a hard circle, ink bleeds: a soft wash of the element's
+ * own pigment diluting outward from the press point, gone before it draws
+ * attention to itself.
+ *
+ * The bleed's CSS lives in the base stylesheet, keyed on
+ * `data-motion~="ink-ripple"`; this module watches presses and marks the
+ * press point. Reduced motion collapses the bleed to a state change, as
+ * everywhere else in the system.
+ *
+ * @module
+ */
+/** Watch for presses anywhere inside `root` (default: the document) and
+ * bleed ink from the press point of the nearest opt-in element. Safe to
+ * call more than once; returns the detach function. */
+export declare function attachInkRipple(root?: HTMLElement): () => void;
+/** Stop watching presses. */
+export declare function detachInkRipple(): void;
+//#endregion
+//#region src/styles/components/index.d.ts
+/** Component style registry — every component contributes its stylesheet
+ * here, keyed by the name wrappers pass to `injectComponentStyle`. */
+export declare const componentStyles: Record<string, string>;
+//#endregion
+//#region src/styles.d.ts
+/** The complete token layer (`@layer bs.tokens`): themes, density, contrast,
+ * typography, motion, z-index, plus the document-level base guard and the
+ * ink-ripple motion grammar. */
+export declare const tokensCss: string;
+/** Inject the token layer into the document head once — the inheritance
+ * root that carries themes, density, and the motion grammar. SSR is a
+ * no-op; for SSR pass `tokensCss` to a head tag instead. */
+export declare function injectTokens(): void;
+/** Inject one component stylesheet (plus the token layer on first use).
+ * Idempotent per component; SSR is a no-op. */
+export declare function injectComponentStyle(key: string): void;
+//#endregion